# syedsalmanshareef1-bot/neet-rank-predictor-backend architecture

> Architecture diagram of the GitHub repository syedsalmanshareef1-bot/neet-rank-predictor-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/syedsalmanshareef1-bot/neet-rank-predictor-backend
- Repository: https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend

## Overview

This is a FastAPI-backed NEET-PG rank predictor and cutoff-data service, with a browser frontend and admin workflows for maintaining counselling data. Students choose filters and submit a rank; the API applies seat eligibility and cutoff matching, then returns ranked college/course results. Admins authenticate, upload cutoff files, review import history and conflicts, and resolve disagreements. The graph reflects documented capabilities and sampled call ownership; some router and frontend implementation details were not included in the excerpts, so uncertain internal links are omitted.

Main entry points: [`app/database.py`](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/database.py) (Database sessions), [`app/main.py`](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/main.py) (FastAPI app), [`app/routers/admin.py`](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/routers/admin.py) (Admin endpoints), [`frontend_dist/js/api.js`](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/frontend_dist/js/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser experience"]
  node_web_app["Predictor UI<br/>[app.js]"]
  node_web_api["API client<br/>[api.js]"]
  node_admin_page["Admin dashboard<br/>[admin.html]"]
  node_auth_ui["Auth helper<br/>[auth.js]"]
end

subgraph group_api["Public API"]
  node_app_entry["FastAPI app<br/>[main.py]"]
  node_predict_route["Prediction endpoint<br/>[predict.py]"]
  node_meta_route["Reference and college API<br/>[meta.py]"]
  node_health_route["Health endpoint<br/>[health.py]"]
  node_auth_route["User authentication<br/>[auth.py]"]
end

subgraph group_prediction["Prediction logic"]
  node_predictor["Rank prediction"]
  node_seat_rules["Seat eligibility rules<br/>[seat_rules.py]"]
end

subgraph group_admin["Admin data management"]
  node_admin_route["Admin endpoints<br/>[admin.py]"]
  node_file_parser["Upload parsers<br/>[file_parsers.py]"]
  node_import_engine["Import and merge<br/>[import_service.py]"]
  node_normalizer["Data normalization<br/>[normalize.py]"]
  node_lookups["Reference lookups<br/>[lookups.py]"]
end

subgraph group_persistence["Persistence"]
  node_database_layer["Database sessions<br/>[database.py]"]
  node_orm_models["Domain records<br/>[models.py]"]
  node_postgres[("PostgreSQL")]
end

node_student(("Student"))
node_admin_user(("Administrator"))

node_student -->|"uses"| node_web_app
node_web_app -->|"requests data"| node_web_api
node_web_api -->|"submits prediction"| node_predict_route
node_web_api -->|"loads choices"| node_meta_route
node_web_api -->|"calls API"| node_app_entry
node_app_entry -->|"dispatches"| node_predict_route
node_app_entry -->|"dispatches"| node_meta_route
node_app_entry -->|"dispatches"| node_health_route
node_app_entry -->|"dispatches"| node_auth_route
node_app_entry -->|"dispatches"| node_admin_route
node_predict_route -->|"runs prediction"| node_predictor
node_predictor -->|"checks eligibility"| node_seat_rules
node_predictor -->|"loads records"| node_database_layer
node_meta_route -->|"queries metadata"| node_database_layer
node_database_layer -->|"maps records"| node_orm_models
node_database_layer -->|"reads and writes"| node_postgres
node_admin_user -->|"uses"| node_admin_page
node_admin_page -->|"checks session"| node_auth_ui
node_admin_page -->|"uploads and reviews"| node_admin_route
node_admin_route -->|"parses upload"| node_file_parser
node_admin_route -->|"imports rows"| node_import_engine
node_import_engine -->|"normalizes keys"| node_normalizer
node_import_engine -->|"resolves references"| node_lookups
node_import_engine -->|"merges records"| node_database_layer
node_admin_route -->|"reads audit and conflicts"| node_database_layer
node_auth_route -->|"checks accounts"| node_database_layer

click node_web_app "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/frontend_dist/js/app.js"
click node_web_api "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/frontend_dist/js/api.js"
click node_admin_page "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/frontend_dist/admin.html"
click node_auth_ui "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/frontend_dist/js/auth.js"
click node_app_entry "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/main.py"
click node_predict_route "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/routers/predict.py"
click node_meta_route "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/routers/meta.py"
click node_health_route "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/routers/health.py"
click node_auth_route "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/routers/auth.py"
click node_admin_route "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/routers/admin.py"
click node_predictor "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/services/predictor_service.py"
click node_seat_rules "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/services/seat_rules.py"
click node_file_parser "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/services/file_parsers.py"
click node_import_engine "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/services/import_service.py"
click node_normalizer "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/services/normalize.py"
click node_lookups "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/services/lookups.py"
click node_database_layer "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/database.py"
click node_orm_models "https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/models.py"

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_web_app,node_web_api,node_admin_page,node_auth_ui toneBlue
class node_app_entry,node_predict_route,node_meta_route,node_health_route,node_auth_route toneAmber
class node_predictor,node_seat_rules toneMint
class node_admin_route,node_file_parser,node_import_engine,node_normalizer,node_lookups toneRose
class node_database_layer,node_orm_models,node_postgres,node_student,node_admin_user toneIndigo
```

## Components

### Browser experience

- [Predictor UI](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/frontend_dist/js/app.js): `frontend_dist/js/app.js`
- [API client](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/frontend_dist/js/api.js): `frontend_dist/js/api.js`
- [Admin dashboard](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/frontend_dist/admin.html): `frontend_dist/admin.html`
- [Auth helper](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/frontend_dist/js/auth.js): `frontend_dist/js/auth.js`

### Public API

- [FastAPI app](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/main.py): `app/main.py`
- [Prediction endpoint](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/routers/predict.py): `app/routers/predict.py`
- [Reference and college API](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/routers/meta.py): `app/routers/meta.py`
- [Health endpoint](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/routers/health.py): `app/routers/health.py`
- [User authentication](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/routers/auth.py): `app/routers/auth.py`

### Prediction logic

- [Rank prediction](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/services/predictor_service.py): `app/services/predictor_service.py`
- [Seat eligibility rules](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/services/seat_rules.py): `app/services/seat_rules.py`

### Admin data management

- [Admin endpoints](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/routers/admin.py): `app/routers/admin.py`
- [Upload parsers](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/services/file_parsers.py): `app/services/file_parsers.py`
- [Import and merge](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/services/import_service.py): `app/services/import_service.py`
- [Data normalization](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/services/normalize.py): `app/services/normalize.py`
- [Reference lookups](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/services/lookups.py): `app/services/lookups.py`

### Persistence

- [Database sessions](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/database.py): `app/database.py`
- [Domain records](https://github.com/syedsalmanshareef1-bot/neet-rank-predictor-backend/blob/main/app/models.py): `app/models.py`
- **PostgreSQL**

### Other components

- **Student**
- **Administrator**

## Connections

- Student → Predictor UI: uses
- Predictor UI → API client: requests data
- API client → Prediction endpoint: submits prediction
- API client → Reference and college API: loads choices
- API client → FastAPI app: calls API
- FastAPI app → Prediction endpoint: dispatches
- FastAPI app → Reference and college API: dispatches
- FastAPI app → Health endpoint: dispatches
- FastAPI app → User authentication: dispatches
- FastAPI app → Admin endpoints: dispatches
- Prediction endpoint → Rank prediction: runs prediction
- Rank prediction → Seat eligibility rules: checks eligibility
- Rank prediction → Database sessions: loads records
- Reference and college API → Database sessions: queries metadata
- Database sessions → Domain records: maps records
- Database sessions → PostgreSQL: reads and writes
- Administrator → Admin dashboard: uses
- Admin dashboard → Auth helper: checks session
- Admin dashboard → Admin endpoints: uploads and reviews
- Admin endpoints → Upload parsers: parses upload
- Admin endpoints → Import and merge: imports rows
- Import and merge → Data normalization: normalizes keys
- Import and merge → Reference lookups: resolves references
- Import and merge → Database sessions: merges records
- Admin endpoints → Database sessions: reads audit and conflicts
- User authentication → Database sessions: checks accounts