# adityakumaaar/josaa-explorer architecture

> Architecture diagram of the GitHub repository adityakumaaar/josaa-explorer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adityakumaaar/josaa-explorer
- Repository: https://github.com/adityakumaaar/josaa-explorer

## Overview

#### 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: [`frontend/src/hooks/useSearch.ts`](https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/hooks/useSearch.ts) (Search State), [`frontend/src/lib/pivotResults.ts`](https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/lib/pivotResults.ts) (Decision Transforms), [`backend/app/api/routes.py`](https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/app/api/routes.py) (API Routes), [`backend/app/services/search.py`](https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/app/services/search.py) (Eligibility Search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React Frontend"]
  node_browser(("Student Browser<br/>user client"))
  node_react_app["React Application<br/>React/Vite app<br/>[App.tsx]"]
  node_search_form["Search Form<br/>input UI<br/>[SearchForm.tsx]"]
  node_search_hook["Search State<br/>React hook<br/>[useSearch.ts]"]
  node_api_client["API Client<br/>frontend API layer<br/>[api.ts]"]
  node_results_views["Eligibility Results<br/>result UI<br/>[ResultsTable.tsx]"]
  node_decision_transforms["Decision Transforms<br/>result adapters<br/>[pivotResults.ts]"]
  node_mind_map["College Mind Map<br/>graph visualization<br/>[CollegeMindMap.tsx]"]
  node_india_map["India College Map<br/>geographic visualization"]
end

subgraph group_api["FastAPI Backend"]
  node_fastapi{{"FastAPI Application<br/>API runtime<br/>[main.py]"}}
  node_routes["API Routes<br/>HTTP endpoints<br/>[routes.py]"]
  node_search_service["Eligibility Search<br/>search service<br/>[search.py]"]
  node_schemas["Domain Contracts<br/>schemas and mappings<br/>[schemas.py]"]
  node_database_layer["Database Setup<br/>SQLAlchemy layer<br/>[database.py]"]
  node_sqlite[("SQLite Admissions Data<br/>runtime datastore")]
end

subgraph group_ingestion["Data Ingestion"]
  node_scrape_runner{{"Scrape Runner<br/>ingestion entry point<br/>[run_scraper.py]"}}
  node_fetchers["JoSAA Fetchers<br/>Playwright retrieval<br/>[fetch_archive.py]"]
  node_parser["Cutoff Parser<br/>record extraction<br/>[parser.py]"]
end

node_josaa_source(("JoSAA Source Site<br/>external admissions source"))
node_deployment["Container Deployment<br/>Docker/Railway deployment"]

node_browser -->|"uses"| node_react_app
node_react_app -->|"composes"| node_search_form
node_search_form -->|"submits criteria"| node_search_hook
node_search_hook -->|"requests search"| node_api_client
node_api_client -->|"/api"| node_routes
node_routes -->|"delegates search"| node_search_service
node_routes -->|"validates contracts"| node_schemas
node_search_service -->|"uses criteria and results"| node_schemas
node_search_service -->|"queries cutoffs"| node_database_layer
node_database_layer -->|"reads"| node_sqlite
node_search_hook -->|"supplies results"| node_results_views
node_search_hook -->|"adapts results"| node_decision_transforms
node_decision_transforms -->|"builds graph data"| node_mind_map
node_decision_transforms -->|"supplies locations"| node_india_map
node_scrape_runner -->|"runs retrieval"| node_fetchers
node_fetchers -->|"automates browser retrieval"| node_josaa_source
node_fetchers -->|"passes pages"| node_parser
node_parser -->|"populates records"| node_sqlite
node_deployment -->|"packages"| node_fastapi
node_deployment -->|"deploys client"| node_react_app

click node_react_app "https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/App.tsx"
click node_search_form "https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/components/SearchForm.tsx"
click node_search_hook "https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/hooks/useSearch.ts"
click node_api_client "https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/lib/api.ts"
click node_results_views "https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/components/ResultsTable.tsx"
click node_decision_transforms "https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/lib/pivotResults.ts"
click node_mind_map "https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/components/mindmap/CollegeMindMap.tsx"
click node_india_map "https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/components/map/IndiaCollegeMap.tsx"
click node_fastapi "https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/app/main.py"
click node_routes "https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/app/api/routes.py"
click node_search_service "https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/app/services/search.py"
click node_schemas "https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/app/models/schemas.py"
click node_database_layer "https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/app/models/database.py"
click node_scrape_runner "https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/run_scraper.py"
click node_fetchers "https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/app/scraper/fetch_archive.py"
click node_parser "https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/app/scraper/parser.py"
click node_deployment "https://github.com/adityakumaaar/josaa-explorer/blob/main/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_react_app,node_search_form,node_search_hook,node_api_client,node_results_views,node_decision_transforms,node_mind_map,node_india_map toneBlue
class node_fastapi,node_routes,node_search_service,node_schemas,node_database_layer,node_sqlite toneAmber
class node_scrape_runner,node_fetchers,node_parser toneMint
class node_josaa_source,node_deployment toneNeutral
```

## Components

### React Frontend

- **Student Browser**: user client · Enters rank, category, state, gender, and preferences.
- [React Application](https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/App.tsx): React/Vite app · `frontend/src/App.tsx`
- [Search Form](https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/components/SearchForm.tsx): input UI · `frontend/src/components/SearchForm.tsx`
- [Search State](https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/hooks/useSearch.ts): React hook · `frontend/src/hooks/useSearch.ts`
- [API Client](https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/lib/api.ts): frontend API layer · `frontend/src/lib/api.ts`
- [Eligibility Results](https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/components/ResultsTable.tsx): result UI · Table and college-card presentation. · `frontend/src/components/ResultsTable.tsx`
- [Decision Transforms](https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/lib/pivotResults.ts): result adapters · Pivots results and generates choice lists. · `frontend/src/lib/pivotResults.ts`
- [College Mind Map](https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/components/mindmap/CollegeMindMap.tsx): graph visualization · `frontend/src/components/mindmap/CollegeMindMap.tsx`
- [India College Map](https://github.com/adityakumaaar/josaa-explorer/blob/main/frontend/src/components/map/IndiaCollegeMap.tsx): geographic visualization · Uses bundled state GeoJSON. · `frontend/src/components/map/IndiaCollegeMap.tsx`

### FastAPI Backend

- [FastAPI Application](https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/app/main.py): API runtime · `backend/app/main.py`
- [API Routes](https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/app/api/routes.py): HTTP endpoints · Search, metadata, listings, and health endpoints under /api. · `backend/app/api/routes.py`
- [Eligibility Search](https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/app/services/search.py): search service · Filters historical cutoffs and produces year-wise eligibility results. · `backend/app/services/search.py`
- [Domain Contracts](https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/app/models/schemas.py): schemas and mappings · API contracts, domain representations, and institute-state normalization. · `backend/app/models/schemas.py`
- [Database Setup](https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/app/models/database.py): SQLAlchemy layer · `backend/app/models/database.py`
- **SQLite Admissions Data**: runtime datastore · Historical opening and closing rank records for 2019–2025.

### Data Ingestion

- [Scrape Runner](https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/run_scraper.py): ingestion entry point · Runs all-year, year, round, or current-year collection. · `backend/run_scraper.py`
- [JoSAA Fetchers](https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/app/scraper/fetch_archive.py): Playwright retrieval · Separate archive and current-year retrieval from the ASP.NET source site. · `backend/app/scraper/fetch_archive.py`
- [Cutoff Parser](https://github.com/adityakumaaar/josaa-explorer/blob/main/backend/app/scraper/parser.py): record extraction · Converts fetched pages into structured cutoff records. · `backend/app/scraper/parser.py`

### Other components

- **JoSAA Source Site**: external admissions source · ASP.NET site with anti-automation behavior.
- [Container Deployment](https://github.com/adityakumaaar/josaa-explorer/blob/main/Dockerfile): Docker/Railway deployment · `Dockerfile`

## Connections

- 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