How adityakumaaar/josaa-explorer works
Purpose and Deployment Shape
JoSAA Explorer matches a student’s rank, category, gender, home state, and preferences against JoSAA opening/closing rank data from 2019–2025. It is a client/server system: a React browser UI calls a FastAPI API backed by SQLite-populated admissions data. Container and Railway deployment artifacts are at Dockerfile and railway.toml.
Backend API Boundary
FastAPI is initialized in backend/app/main.py; HTTP endpoints are defined in backend/app/api/routes.py. The API exposes search, metadata, institute/program listings, and health checks under /api. The frontend accesses this boundary through frontend/src/lib/api.ts; local Vite development proxies /api to the backend.
Search and Eligibility Core
Search orchestration belongs to backend/app/services/search.py, with request/response contracts in backend/app/models/schemas.py. This layer translates user criteria into database filters over historical cutoff records, determines eligible choices, and produces year-wise results/confidence-oriented data for the UI. Sentiment and future AI-adjacent service boundaries exist in backend/app/services/sentiment.py and backend/app/services/ai.py, though the documented AI API namespace is reserved for future use.
Persistence and Domain Model
SQLAlchemy/database setup is centralized in backend/app/models/database.py. Core domain representations and API schemas are in backend/app/models/schemas.py, while state normalization/mapping is represented by backend/app/models/institute_states.py. SQLite is the stated runtime datastore; scraper processes populate it before search traffic is served.
Data Acquisition Pipeline
Playwright browser automation handles JoSAA’s ASP.NET/anti-automation source site. Historical and current-year retrieval are separated in backend/app/scraper/fetch_archive.py and backend/app/scraper/fetch_current.py; extracted pages are converted into structured records by backend/app/scraper/parser.py. backend/run_scraper.py is the principal ingestion entry point, supporting all-year, year, round, and current-year runs. Alternative batch/deployment scrape runners include backend/scrape_all_parallel.py and backend/scrape_deploy.py.
Frontend Search Experience
The React/Vite entry point is frontend/src/main.tsx, with application composition in frontend/src/App.tsx. frontend/src/hooks/useSearch.ts owns search request state and invokes the API client. User input is collected in frontend/src/components/SearchForm.tsx; returned eligibility data is presented through frontend/src/components/ResultsTable.tsx and frontend/src/components/CollegeCard.tsx.
Derived Decision Visualizations
Frontend transformation logic adapts API search results to distinct views: pivoting and generated choice lists in frontend/src/lib/pivotResults.ts and frontend/src/lib/generateChoiceList.ts, plus mind-map graph construction in frontend/src/lib/buildMindMapGraph.ts. The graph UI is rendered by frontend/src/components/mindmap/CollegeMindMap.tsx. Geographic display combines institute/state data with the bundled India GeoJSON asset at frontend/public/maps/india-states.geojson, rendered by frontend/src/components/map/IndiaCollegeMap.tsx.
Main entry points: useSearch.ts Search State · pivotResults.ts Decision Transforms · routes.py API Routes · search.py Eligibility Search
Components 20
React Frontend
- Student Browser · Enters rank, category, state, gender, and preferences.
- React Application
frontend/src/App.tsx - Search Form
frontend/src/components/SearchForm.tsx - Search State
frontend/src/hooks/useSearch.ts - API Client
frontend/src/lib/api.ts - Eligibility Results · Table and college-card presentation.
frontend/src/components/ResultsTable.tsx - Decision Transforms · Pivots results and generates choice lists.
frontend/src/lib/pivotResults.ts - College Mind Map
frontend/src/components/mindmap/CollegeMindMap.tsx - India College Map · Uses bundled state GeoJSON.
frontend/src/components/map/IndiaCollegeMap.tsx
FastAPI Backend
- FastAPI Application
backend/app/main.py - API Routes · Search, metadata, listings, and health endpoints under /api.
backend/app/api/routes.py - Eligibility Search · Filters historical cutoffs and produces year-wise eligibility results.
backend/app/services/search.py - Domain Contracts · API contracts, domain representations, and institute-state normalization.
backend/app/models/schemas.py - Database Setup
backend/app/models/database.py - SQLite Admissions Data · Historical opening and closing rank records for 2019–2025.
Data Ingestion
- Scrape Runner · Runs all-year, year, round, or current-year collection.
backend/run_scraper.py - JoSAA Fetchers · Separate archive and current-year retrieval from the ASP.NET source site.
backend/app/scraper/fetch_archive.py - Cutoff Parser · Converts fetched pages into structured cutoff records.
backend/app/scraper/parser.py
Other components
- JoSAA Source Site · ASP.NET site with anti-automation behavior.
- Container Deployment
Dockerfile
Connections 20
- Student Browser → React Application: uses
- React Application → Search Form: composes
- Search Form → Search State: submits criteria
- Search State → API Client: requests search
- API Client → API Routes: /api
- API Routes → Eligibility Search: delegates search
- API Routes → Domain Contracts: validates contracts
- Eligibility Search → Domain Contracts: uses criteria and results
- Eligibility Search → Database Setup: queries cutoffs
- Database Setup → SQLite Admissions Data: reads
- Search State → Eligibility Results: supplies results
- Search State → Decision Transforms: adapts results
- Decision Transforms → College Mind Map: builds graph data
- Decision Transforms → India College Map: supplies locations
- Scrape Runner → JoSAA Fetchers: runs retrieval
- JoSAA Fetchers → JoSAA Source Site: automates browser retrieval
- JoSAA Fetchers → Cutoff Parser: passes pages
- Cutoff Parser → SQLite Admissions Data: populates records
- Container Deployment → FastAPI Application: packages
- Container Deployment → React Application: deploys client