@@ -4,32 +4,32 @@ A responsive Web GUI dashboard application designed to automate the housing lott
...
@@ -4,32 +4,32 @@ A responsive Web GUI dashboard application designed to automate the housing lott
---
---
## 1. Directory Structure
## 1. How to Run
```text
### On Windows (Detailed Step-by-Step Guide):
app/
If you have never used Python before, don't worry! Follow these simple instructions to set it up on your computer:
├── allocator.py # Core allocation and priority pooling rules engine
├── server.py # Flask HTTP Web Server handling JSON APIs
├── run.sh # Startup script for Linux/macOS
├── run.bat # Startup script for Windows CMD
├── README.md # Usage instructions (this file)
└── templates/
└── index.html # HTML5 Single Page Application Web Dashboard UI
```
---
#### Part A: Install Python (First-Time Setup Only)
1.**Download the Installer**: Open your web browser, go to [https://www.python.org/downloads/](https://www.python.org/downloads/), and click the big yellow button that says **"Download Python 3.x.x"**.
2.**Start the Installation**: Double-click the downloaded setup file (usually named `python-3.x.x-amd64.exe` in your Downloads folder) to open the installer.
3.**CRITICAL STEP (Add to PATH)**: In the installation window that pops up, **look at the very bottom** and check the checkbox that says:
`[✓] Add python.exe to PATH`
*(Please make sure this is checked! If you miss this step, the batch runner script will not be able to find Python on your computer).*
4.**Finish Setup**: Click the big **"Install Now"** button. If Windows asks for administrative permission, click **Yes**. Once the progress bar completes, click **Close**.
## 2. Prerequisites
---
The application requires **Python 3** and the following packages:
#### Part B: Launch the Portal
-**Flask**
1. Open the folder where this project is saved on your computer (e.g. inside your Documents or Desktop).
-**Pandas**
2. Double-click the file named [**run.bat**](file:///home/prayush/Documents/ICTS/ICTSHousingCell/icts-housing/app/run.bat) inside the `app/` folder.
-**Numpy**
3. A black command prompt window will open. On the first launch, it will automatically download and install standard Excel/Web parsing packages (`Flask`, `pandas`, `numpy`). This takes around 15 seconds.
4.**Keep this black command prompt window open** in the background (closing this window will stop the application engine).
5. Open your web browser (Chrome, Edge, Firefox, etc.) and type this address into the top URL bar:
6. To stop the application when you are finished, simply close the browser page and close the black command window.
---
---
## 3. How to Run
### On Linux / macOS:
### On Linux / macOS:
1. Open a terminal inside the cloned repository root folder.
1. Open a terminal inside the cloned repository root folder.
2. Make `run.sh` executable and run it:
2. Make `run.sh` executable and run it:
...
@@ -39,15 +39,9 @@ The application requires **Python 3** and the following packages:
...
@@ -39,15 +39,9 @@ The application requires **Python 3** and the following packages:
```
```
3. Open your browser and navigate to: [http://localhost:5000](http://localhost:5000)
3. Open your browser and navigate to: [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)
---
---
## 4. Web Dashboard Features
## 2. Web Dashboard Features
- **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.
...
@@ -55,3 +49,27 @@ The application requires **Python 3** and the following packages:
...
@@ -55,3 +49,27 @@ The application requires **Python 3** and the following packages:
- **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.
- **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 or standard `.csv` files.
- **Raw Export**: Download the generated allotment tables in`.txt` format or standard `.csv` files.
---
## 3. Prerequisites
The application requires **Python 3** and the following packages:
- **Flask**
- **Pandas**
- **Numpy**
---
## 4. Directory Structure
```text
app/
├── allocator.py # Core allocation and priority pooling rules engine
├── server.py # Flask HTTP Web Server handling JSON APIs
├── run.sh # Startup script for Linux/macOS
├── run.bat # Startup script for Windows CMD
├── README.md # Usage instructions (this file)
└── templates/
└── index.html # HTML5 Single Page Application Web Dashboard UI
