How bulktornado/josaa-rank-analyser-2025 works
1. What this repository is
- This is a data extraction and packaging repo for JoSAA seat allotment results, not an application server or web app.
- The primary deliverables are:
- an Excel workbook: JoSAA All Rounds Seat Allotment Result.xlsx
- a SQLite database: JoSAA_Seat_Allotment.db
- per-round CSV exports for rounds 1–6 and selected category slices
2. External data source boundary
- The source data comes from the JoSAA website referenced in the README.
- The repo appears to consume downloaded result data and transform it locally; there is no sign of a hosted backend or live API inside the repo.
3. Main processing entrypoint
- main.py is the likely orchestration script.
- It is the central place where parsing, normalization, and export steps would be coordinated, with outputs written to CSV, SQLite, and/or Excel-related artifacts.
4. Parsing/normalization layer
- JoSAA_Result_Parser.py is the core transformation component.
- Its role is likely to:
- read source result data
- normalize row/column structure
- split the data by round and category
- emit structured outputs for downstream analysis
5. Persistent data model
- JoSAA_Seat_Allotment.db is the structured storage layer for advanced querying.
- The README explicitly positions SQLite as the preferred backend for users comfortable with SQL or the sqlite3 CLI.
- This means the repo supports both file-based analysis and database-backed querying.
6. Exported analytical views
- The numerous CSV files are derived artifacts, organized by:
- round: Round_1 through Round_6
- slice: ALL, OPEN, OBC-NCL
- These CSVs are likely denormalized views intended for spreadsheet tools or simple scripting workflows.
7. Excel-first consumption path
- JoSAA All Rounds Seat Allotment Result.xlsx is the most user-friendly output and is emphasized in the README as the easiest access path.
- This makes the Excel workbook the primary “distribution format” for non-technical users, with sorting/filtering done in Excel rather than through code.
8. Reference and lookup data
- academic_programs.txt likely contains a catalog of program names or mappings used during parsing/cleanup.
- sql_query.txt suggests sample or working SQL queries for querying the SQLite database.
- notes.txt likely contains ad hoc data-cleaning or domain notes used during transformation.
9. Data correction / cleanup scripts
- The fix_database.py, fix_p.py, and fix_trailing_zero.py scripts indicate post-processing utilities rather than the main pipeline.
- These likely address issues such as:
- database repair or schema correction
- parsing quirks
- normalization of numeric formatting, especially rank/value formatting
10. Technology stack
- The project is Python-based, as indicated by pyproject.toml, .python-version, and the .py scripts.
- The presence of SQLite DB output strongly suggests use of Python’s SQLite tooling or equivalent library support.
- The repo is centered on local file generation rather than runtime services.
11. Primary data flow
- Source JoSAA data → parser/cleanup scripts → structured internal dataset → exports to:
- SQLite database for querying
- CSV files for lightweight analysis
- Excel workbook for general consumption
12. Operational boundary
- There is no evidence of authentication, background jobs, message queues, web UI, or cloud infrastructure.
- The system is a single-machine ETL/packaging workflow: ingest, clean, store, export.
13. How to draw the architecture
- A clear diagram would show:
- JoSAA website / downloaded spreadsheet on the left
- Python parsing and fix scripts in the middle
- SQLite DB + CSV files + Excel workbook on the right as output sinks
- The main conceptual split is between raw downloaded data, transformation logic, and consumable outputs.
Main entry points: JoSAA_Result_Parser.py Parser · main.py Main · pyproject.toml Py project · JoSAA_Seat_Allotment.db SQLite DB
Components 15
Source data
External JoSAA result data consumed by the repo
- JoSAA site · Downloaded seat allotment results from the JoSAA website
Processing
Parsing, cleanup, and orchestration scripts
- Main · Coordinates parsing, cleanup, and export steps
main.py - Parser · Core normalization and extraction logic for seat allotment data
JoSAA_Result_Parser.py - Fix DB · Database repair or correction utility
fix_database.py - Fix parse · Parsing cleanup utility for edge cases
fix_p.py - Fix zeroes · Normalizes trailing-zero and numeric formatting issues
fix_trailing_zero.py
Outputs
Packaged analytical artifacts for users
- SQLite DB · Queryable seat allotment database
JoSAA_Seat_Allotment.db - Excel workbook · Primary end-user workbook for all rounds
JoSAA All Rounds Seat Allotment Result.xlsx - Round CSVs · Per-round CSV exports for rounds 1 through 6
- Category CSVs · Filtered CSV exports such as ALL, OPEN, and OBC-NCL
Reference
Lookup data, notes, and example queries
- Programs · Academic program catalog or mapping used during parsing
academic_programs.txt - SQL queries · Example or working queries for the SQLite database
sql_query.txt - Notes · Ad hoc cleanup and domain-specific reference notes
notes.txt - README · Explains the data flow, outputs, and usage patterns
README.md - Py project · Project metadata and dependency configuration
pyproject.toml
Connections 15
- JoSAA site → Main: downloaded data · Source results are ingested by the orchestration entrypoint
- Main → Parser: invokes · Main script delegates extraction and normalization
- Parser → Fix parse: cleanup · Parsing issues are handled by repair utilities
- Parser → Fix zeroes: cleanup · Numeric formatting is normalized during post-processing
- Parser → Fix DB: repair · Structured data can be corrected before or after database writes
- Parser → SQLite DB: load · Normalized records are stored for querying
- Parser → Round CSVs: export · Round-wise CSV views are generated
- Parser → Category CSVs: export · Category-filtered CSV slices are generated
- Parser → Excel workbook: package · Workbook output is assembled for general consumption
- Programs → Parser: lookup · Program names or mappings support normalization
- Notes → Parser: guidance · Domain notes inform cleanup and transformation rules
- SQL queries → SQLite DB: querying · SQL notes support direct database analysis
- README → Main: documents · Repository usage and output flow are described here
- Py project → Main: runtime setup · Python project configuration supports execution
- Py project → Parser: runtime setup · Python project configuration supports execution