# bulktornado/josaa-rank-analyser-2025 architecture

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

- Interactive diagram: https://gitdiagram.com/bulktornado/josaa-rank-analyser-2025
- Repository: https://github.com/bulktornado/josaa-rank-analyser-2025

## Overview

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`](https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/JoSAA_Result_Parser.py) (Parser), [`main.py`](https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/main.py) (Main), [`pyproject.toml`](https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/pyproject.toml) (Py project), [`JoSAA_Seat_Allotment.db`](https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/JoSAA_Seat_Allotment.db) (SQLite DB)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Source data"]
  node_josaa_site["JoSAA site<br/>external source"]
end

subgraph group_pipeline["Processing"]
  node_main_py["Main<br/>orchestrator<br/>[main.py]"]
  node_parser_py["Parser<br/>transformer"]
  node_fix_db_py["Fix DB<br/>repair script<br/>[fix_database.py]"]
  node_fix_p_py["Fix parse<br/>repair script<br/>[fix_p.py]"]
  node_fix_zero_py["Fix zeroes<br/>cleanup script"]
end

subgraph group_outputs["Outputs"]
  node_sqlite_db[("SQLite DB<br/>structured store")]
  node_excel_xlsx["Excel workbook<br/>distribution file"]
  node_csv_rounds["Round CSVs<br/>exported views"]
  node_csv_slices["Category CSVs<br/>exported slices"]
end

subgraph group_reference["Reference"]
  node_academic_txt["Programs<br/>lookup data"]
  node_sql_txt["SQL queries<br/>query notes<br/>[sql_query.txt]"]
  node_notes_txt["Notes<br/>[notes.txt]"]
  node_readme_md["README<br/>documentation<br/>[README.md]"]
  node_pyproject["Py project<br/>python config<br/>[pyproject.toml]"]
end

node_josaa_site -->|"downloaded data"| node_main_py
node_main_py -->|"invokes"| node_parser_py
node_parser_py -.->|"cleanup"| node_fix_p_py
node_parser_py -.->|"cleanup"| node_fix_zero_py
node_parser_py -.->|"repair"| node_fix_db_py
node_parser_py -->|"load"| node_sqlite_db
node_parser_py -->|"export"| node_csv_rounds
node_parser_py -->|"export"| node_csv_slices
node_parser_py -->|"package"| node_excel_xlsx
node_academic_txt -.->|"lookup"| node_parser_py
node_notes_txt -.->|"guidance"| node_parser_py
node_sql_txt -.->|"querying"| node_sqlite_db
node_readme_md -.->|"documents"| node_main_py
node_pyproject -.->|"runtime setup"| node_main_py
node_pyproject -.->|"runtime setup"| node_parser_py

click node_main_py "https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/main.py"
click node_parser_py "https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/JoSAA_Result_Parser.py"
click node_fix_db_py "https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/fix_database.py"
click node_fix_p_py "https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/fix_p.py"
click node_fix_zero_py "https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/fix_trailing_zero.py"
click node_sqlite_db "https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/JoSAA_Seat_Allotment.db"
click node_excel_xlsx "https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/JoSAA All Rounds Seat Allotment Result.xlsx"
click node_academic_txt "https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/academic_programs.txt"
click node_sql_txt "https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/sql_query.txt"
click node_notes_txt "https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/notes.txt"
click node_readme_md "https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/README.md"
click node_pyproject "https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/pyproject.toml"

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_josaa_site toneBlue
class node_main_py,node_parser_py,node_fix_db_py,node_fix_p_py,node_fix_zero_py toneAmber
class node_sqlite_db,node_excel_xlsx,node_csv_rounds,node_csv_slices toneMint
class node_academic_txt,node_sql_txt,node_notes_txt,node_readme_md,node_pyproject toneRose
```

## Components

### Source data

External JoSAA result data consumed by the repo

- **JoSAA site**: external source · Downloaded seat allotment results from the JoSAA website

### Processing

Parsing, cleanup, and orchestration scripts

- [Main](https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/main.py): orchestrator · Coordinates parsing, cleanup, and export steps · `main.py`
- [Parser](https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/JoSAA_Result_Parser.py): transformer · Core normalization and extraction logic for seat allotment data · `JoSAA_Result_Parser.py`
- [Fix DB](https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/fix_database.py): repair script · Database repair or correction utility · `fix_database.py`
- [Fix parse](https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/fix_p.py): repair script · Parsing cleanup utility for edge cases · `fix_p.py`
- [Fix zeroes](https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/fix_trailing_zero.py): cleanup script · Normalizes trailing-zero and numeric formatting issues · `fix_trailing_zero.py`

### Outputs

Packaged analytical artifacts for users

- [SQLite DB](https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/JoSAA_Seat_Allotment.db): structured store · Queryable seat allotment database · `JoSAA_Seat_Allotment.db`
- [Excel workbook](https://github.com/bulktornado/josaa-rank-analyser-2025/blob/HEAD/JoSAA%20All%20Rounds%20Seat%20Allotment%20Result.xlsx): distribution file · Primary end-user workbook for all rounds · `JoSAA All Rounds Seat Allotment Result.xlsx`
- **Round CSVs**: exported views · Per-round CSV exports for rounds 1 through 6
- **Category CSVs**: exported slices · Filtered CSV exports such as ALL, OPEN, and OBC-NCL

### Reference

Lookup data, notes, and example queries

- [Programs](https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/academic_programs.txt): lookup data · Academic program catalog or mapping used during parsing · `academic_programs.txt`
- [SQL queries](https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/sql_query.txt): query notes · Example or working queries for the SQLite database · `sql_query.txt`
- [Notes](https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/notes.txt): domain notes · Ad hoc cleanup and domain-specific reference notes · `notes.txt`
- [README](https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/README.md): documentation · Explains the data flow, outputs, and usage patterns · `README.md`
- [Py project](https://github.com/bulktornado/josaa-rank-analyser-2025/blob/main/pyproject.toml): python config · Project metadata and dependency configuration · `pyproject.toml`

## Connections

- 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