BharatGenome

A population-aware genomic research interface that compares Indian and global genomic evidence — and makes the difference understandable.

Research and educational prototype. Not a clinical tool. It does not provide diagnosis, treatment advice, disease prediction, or clinical decision support.

Live: https://bharatgenome.vercel.app

---

The problem

Modern genomic reference resources are built from the populations that were sequenced, and those populations do not represent India's genetic diversity in proportion to its size or its population structure.

That matters because a genomic number is always a statement about a group:

• Allele frequencies differ between populations. A global average can be materially wrong for an Indian population.
• The error travels downstream. Variant filtering thresholds, imputation reference panels, GWAS findings, and polygenic risk scores all inherit the population they were built on. Findings do not automatically transfer.

The solution

BharatGenome puts Indian population evidence next to global reference evidence for the same query, explains the difference in plain language, links supporting literature, and states the provenance, confidence, and limits of every figure.

When a provider has no data, BharatGenome says so. It never estimates a value it cannot source.

Core user journey

Search a gene / variant / rsID
  ↓  Indian population evidence      ┐
  ↓  Global reference evidence       ┘ side by side
  ↓  Allele frequency differences, explained
  ↓  Supporting literature with population context
  ↓  Provenance, confidence, and limitations

What's in the product

Route	What it is
/	The problem, the solution, and how a comparison reads.
/explore	The product. Gene / variant / rsID search and the full comparison result.
/learn-genomics	A supporting educational section: 22 concepts from DNA to population representation. (/learn redirects here.)
/methodology	What is compared, how, live provider status, and the limits of this version.

Learn Genomics is a supporting section inside BharatGenome, not the product.

---

Running it locally

Requires Node.js 20+ and Python 3.12+.

# 1. Frontend
npm install
cp .env.example .env.local        # everything is optional; defaults work
npm run dev                       # http://localhost:3000

# 2. Backend (separate terminal)
python3 -m venv backend/.venv
backend/.venv/bin/pip install -r backend/requirements-dev.txt
npm run dev:api                   # http://localhost:8000

Point the frontend at the local backend by setting, in .env.local:

NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8000

On Vercel this is left empty: vercel.json rewrites /api/* to the Python function, so the browser calls the same origin.

Checks

npm run build       # Next.js production build
npm run typecheck   # tsc --noEmit
npm run lint        # eslint
npm run test:api    # pytest

cd backend && .venv/bin/ruff check . && .venv/bin/mypy

---

Architecture

src/                        Next.js App Router frontend
├── app/                    routes: /, /explore, /learn-genomics, /methodology
├── components/             shared UI primitives
├── features/
│   ├── explore/            the result workflow
│   ├── genomic-search/     search input
│   ├── population-comparison/  allele frequency bars, comparison panel
│   ├── literature/         literature cards
│   ├── learn-genomics/     educational concepts
│   └── methodology/        live provider status
└── lib/                    API client + the shared domain contract (types.ts)

backend/app/                FastAPI backend
├── schemas.py              the contract, mirroring src/lib/types.ts
├── providers/              GenomicProvider and its scoped subclasses
├── comparison/engine.py    the comparison layer
├── literature/             LiteratureProvider → PubMedProvider
└── services/analysis.py    orchestration for /api/analyze

api/index.py                Vercel entrypoint that serves the FastAPI app
supabase/                   config + migrations (application metadata only)

Provider and comparison abstractions:

GenomicProvider                    ComparisonEngine
├── IndianPopulationProvider       ├── allele-frequency comparison
├── GlobalReferenceProvider        ├── population comparison
└── FuturePopulationProvider       ├── coverage / availability comparison
                                   └── evidence assessment
LiteratureProvider
└── PubMedProvider

Details: docs/architecture.md · docs/methodology.md · docs/data-providers.md · docs/contributing.md

API

Endpoint	Purpose
GET /api/health	Version and the configured/unconfigured state of every provider.
POST /api/analyze	{query, kind} → identity, Indian and global evidence, comparison, evidence, literature, provenance, limitations.
POST /api/literature/search	{query, population_context, limit} → literature results.

---

No genomic datasets are bundled — deliberately

This repository contains no downloaded genomic datasets and no synthetic genomic data standing in for one. GenomeIndia, IndiGen, gnomAD and similar resources are not vendored here.

Instead the repository ships provider contracts. A provider is the only component permitted to produce a genomic number, and each is off until its endpoint environment variable is set. With none set, the application runs and reports:

No live genomic provider is configured yet.

That is the honest state, and it is preferred to a plausible-looking number. The one set of invented figures anywhere in the product is the teaching example on the home page, which is visibly labelled "Illustrative example — not real data".

---

Environment variables

Copy .env.example to .env.local. All are optional; nothing is required to run the app.

Variable	Scope	Purpose
NEXT_PUBLIC_API_BASE_URL	browser	API origin. Empty = same origin.
INDIAN_PROVIDER_ENDPOINT / _API_KEY	server	Indian population provider.
GLOBAL_PROVIDER_ENDPOINT / _API_KEY	server	Global reference provider.
PUBMED_BASE_URL / PUBMED_API_KEY	server	Literature provider.
BHARATGENOME_ALLOWED_ORIGINS	server	CORS origins, comma separated.
NEXT_PUBLIC_SUPABASE_URL / _ANON_KEY	browser	Supabase client (RLS enforced).
SUPABASE_SERVICE_ROLE_KEY	server only	Bypasses RLS. Never NEXT_PUBLIC_.

Only NEXT_PUBLIC_* variables reach the browser. API keys and the service role key are server-side only and must never be given that prefix.

Supabase

Supabase stores application metadata only. No individual-level genetic data is stored anywhere in the system.

supabase link --project-ref <your-project-ref>
supabase db push

Tables (supabase/migrations/):

• provider_registry — which providers exist and which env var enables each (descriptive only, never credentials). Publicly readable.
• search_events — which identifiers were looked up and whether providers answered. No user identifiers, no genetic data. RLS: service role only.
• literature_cache — cached literature responses. RLS: service role only.
• app_metadata — key/value application state. Publicly readable.

RLS is enabled on every table and defaults to deny; the two tables without a policy are unreachable by anon and authenticated clients.

Deployment

Frontend and backend deploy together as one Vercel project:

• Next.js is built by the framework preset.
• api/index.py is deployed as a Python function serving the FastAPI app, with requirements.txt at the repository root.
• vercel.json rewrites /api/* to that function.

vercel link
vercel env add INDIAN_PROVIDER_ENDPOINT production   # optional, when available
vercel --prod

Server-side variables must be added without the NEXT_PUBLIC_ prefix so they are never bundled into client JavaScript.

---

Current limitations

• No genomic provider is connected yet, so Explore reports absence rather than results. That is the intended state of this build.
• No literature provider is connected yet, so no papers are listed.
• "Indian" is currently a single aggregate scope. Real Indian population structure is regional, and the aggregate is a simplification the UI states on every result.
• Confidence is derived from data availability and sample size only.

What teammates can implement next

Area	Start here
Indian / global providers	backend/app/providers/ + docs/data-providers.md
Literature	backend/app/literature/pubmed.py — only search() needs filling in
Comparison & visualisation	backend/app/comparison/engine.py, src/features/population-comparison/
Learn Genomics	src/features/learn-genomics/concepts.tsx
Integration & polish	src/features/explore/, backend/app/services/analysis.py

See CONTRIBUTING.md for branching, PR expectations, and the step-by-step for adding a provider.