A responsive, responsive Web GUI dashboard application designed to automate the housing lottery allocation process for Postdoctoral Fellows and Graduate Students based on the priority pool policies of the ICTS Housing Cell.
A responsive Web GUI dashboard application designed to automate the housing lottery allocation process for Postdoctoral Fellows and Graduate Students based on the priority pool policies of the ICTS Housing Cell.
---
---
## 1. Directory Structure
## 1. Directory Structure
```text
```text
2026/app/
app/
├── allocator.py # Core allocation and priority pooling rules engine
├── allocator.py # Core allocation and priority pooling rules engine
├── server.py # Flask HTTP Web Server handling JSON APIs
├── server.py # Flask HTTP Web Server handling JSON APIs
├── run.sh # Startup script to initialize the application via terminal
├── run.sh # Startup script for Linux/macOS
├── README.md # Usage instructions and logic details (this file)
├── run.bat # Startup script for Windows CMD
├── README.md # Usage instructions (this file)
└── templates/
└── templates/
└── index.html # HTML5 Single Page Application Web Dashboard UI
└── index.html # HTML5 Single Page Application Web Dashboard UI
```
```
---
---
## 2. Requirements
## 2. Prerequisites
The application runs using the system's base conda environment which contains all required dependencies:
The application requires **Python 3** and the following packages:
-**Python 3**
-**Flask**
-**Flask**
-**Pandas**
-**Pandas**
-**Numpy**
-**Numpy**
---
---
## 3. How to Run the Web Application
## 3. How to Run
1. Open your terminal.
### On Linux / macOS:
2. Run the startup script directly:
1. Open a terminal inside the cloned repository root folder.
2. Make `run.sh` executable and run it:
```bash
```bash
./2026/app/run.sh
chmod +x app/run.sh
./app/run.sh
```
```
3. Open your browser and navigate to:
3. Open your browser and navigate to: [http://localhost:5000](http://localhost:5000)
[http://localhost:5000](http://localhost:5000)
### On Windows:
1. Make sure Python 3 is installed and added to your system `PATH`.
2. Double-click the script file [run.bat](file:///home/prayush/Documents/ICTS/ICTSHousingCell/icts-housing/app/run.bat) inside the `app/` folder.
*(This script will automatically check/install `Flask`, `pandas`, and `numpy` via `pip` and start the server).*
3. Open your browser and navigate to: [http://localhost:5000](http://localhost:5000)
---
---
...
@@ -45,6 +52,6 @@ The application runs using the system's base conda environment which contains al
...
@@ -45,6 +52,6 @@ The application runs using the system's base conda environment which contains al
-**Toggle Mode**: Switch seamlessly between **Postdocs** and **Graduate Students** allocation models.
-**Toggle Mode**: Switch seamlessly between **Postdocs** and **Graduate Students** allocation models.
-**CSV Response Upload**: Drag-and-drop the standard responses CSV files (from Google Forms) directly into the portal.
-**CSV Response Upload**: Drag-and-drop the standard responses CSV files (from Google Forms) directly into the portal.
-**Interactive Capacity Configuration**: Adjust the available slots for each housing category (such as hostels or apartments) in real time before triggering the lottery.
-**Interactive Capacity Configuration**: Adjust the available slots for each housing category (such as hostels or apartments) in real time before triggering the lottery.
-**Custom Lottery Seed**: Enter a custom integer seed (e.g. `1780813800` or date seed) to get fully reproducible allotment order.
-**Custom Date-to-Seed Tool**: Select a date and time to automatically compute and convert into the correct corresponding local timestamp seed, or specify an integer/random seed.
-**Interactive Results Table**: Browse allocations instantly. Filter, search by candidate name/email, and verify their satisfied preference rank or unallocated status.
-**Interactive Results Table**: Browse allocations instantly. Filter, search by candidate name/email, and verify their satisfied preference rank or unallocated status.
-**Raw Export**: Download the generated allotment tables in `.txt` format (compatible with the existing format) or standard `.csv` files.
-**Raw Export**: Download the generated allotment tables in `.txt` format or standard `.csv` files.
<li>Select <strong>Postdocs</strong> or <strong>Students</strong> at the top.</li>
<li>Drag & drop the Google Form responses <strong>.csv file</strong> into the upload box.</li>
<li>Edit the numbers in <strong>Housing Category Capacities</strong> to match actual room vacancies if needed.</li>
<li>To run a new draw, click <strong>Gen Random</strong>. To repeat a previous official draw, select the official datetime and click <strong>Convert</strong>.</li>
<li>Open the folder where this project is saved on your computer.</li>
<li>Double-click the file named <strong>run.bat</strong> inside the <code>app</code> folder.</li>
<li>A black command prompt window will open and configure Python requirements automatically.</li>
<li>Keep that black window open. Go to your browser and open <ahref="http://localhost:5000"target="_blank"style="color: var(--primary); text-decoration: none; font-weight: 600;">http://localhost:5000</a>.</li>
