Skip to content

Dev Docs

Jump to bottom
Aquila edited this page Oct 18, 2023 · 4 revisions

Welcome to Exam Hall Seat Allocator!

Exam Hall Seat Allocator (EHSA) is an application built in Rust, Flutter, and Python that automates the allocation of student seats during examinations. The application simplifies the process for educational institutions by efficiently separating students by subjects and classes and generating PDFs containing the seat assignments.

Files and Components

Here’s a brief overview of the various files and components within the GitHub repository:

  • allocator: This is the Rust component of EHSA that handles the seat assignment algorithm.
  • ehsa_frontend: This is the Flutter component of EHSA that handles the front-end of the application.
  • pdf_generator: This is the Python component of EHSA that generates PDFs containing seat assignments.
  • build_flutter_win.bat: This is a batch file that builds the Flutter component for Windows.
  • build_python_win.bat: This is a batch file that builds the Python component for Windows.
  • build_rust_release.bat: This is a batch file that builds the Rust component for release.
  • nsis_script.nsi: This is an NSIS script that combines all three .exe files into a single .exe file.

Quick Navigation:

  1. The Allocator
  2. The pdf Generator
  3. The Flutter Component

System Requirements and Installation

Do refer the readme section in our GitHub Repository!

Click here : EHSA.

The Allocator

The Allocator is the core component of the exam hall seat allocation system, responsible for efficiently distributing students across examination halls .
It utilizes three distinct allocation modes to achieve optimal seat assignments:

Allocation Modes:

  1. Separate Subject: This mode aims to distribute students across examination halls based on the subject. It works by placing students from subjects that haven’t been allocated yet or subjects that have more students.
  2. Separate Class: This mode aims to distribute students across examination halls based on classes. It works by placing students from classes that haven’t been allocated yet.
  3. Any : Any students that weren’t allocated in the previous modes are allocated in roll number order across the remaining halls.

main.rs

The main entry point of the application is main(), which handles the allocation process. The code reads command-line arguments, connects to an SQLite database for input data, and implements the core allocation logic.

Code Structure

Here’s an overview of the key components and their purposes within main.rs:

Command-Line Arguments (args Module)

Purpose and Functionality :The code uses the args module to manage and parse command-line arguments. These arguments influence the program’s behavior, including the randomization of seat allocation.

Functions Used

  • args::get(): Retrieves and parses command-line arguments.

Database Operations (db Module)

Purpose and Functionality : The db module contains functions for reading and writing data to the SQLite database. It includes operations like reading hall and student information, as well as writing the allocation report.

Functions Used

  • db::read_students_table(): Reads student information from the database.
  • db::read_halls_table(): Reads hall information from the database.
  • db::write_report_table(): Writes the allocation report to the output database.

Hall and Student Definitions (hall and student Modules)

Purpose and Functionality : The hall and student modules define the Hall and Student structs, respectively. These structs represent examination halls and individual students, and they are used to organize and manipulate data throughout the allocation process.

Functions Used

  • Hall::new(): Creates a new Hall instance.
  • hall::push(): Adds a student to a hall if there is available space.
  • hall::push_empty(): Adds an empty seat to a hall if there is available space.
  • Student::new(): Creates a new Student instance.

Core Allocation Logic

Purpose and Functionality : The core allocation logic resides within the main() function. It reads students and hall information, implements the allocation process, handles scenarios like empty seats, and writes the allocation report.

Functions Used

get_next_student

Purpose and Functionality: Retrieves the next student to be allocated to a hall.

Arguments:

  • students: &mut HashMap<String, Vec<Student>>: A mutable reference to a hash map containing students organized by a key (subject or class).
  • key: &str: The key (subject or class) from which to retrieve the next student.

get_next_key

Purpose and Functionality: Determines the next key (class or subject) to be used for student allocation.

Arguments:

  • students: &HashMap<String, Vec<Student>>: A reference to a hash map containing students organized by a key (subject or class).
  • placed_keys: &HashSet<String>: A reference to a set containing keys that have already been allocated.
  • previously_placed_key: Option<&String>: An optional reference to the key that was previously used for allocation.

log_sparse_halls

Purpose and Functionality: Logs information about examination halls with low student counts (debug mode).

Arguments:

  • halls: &[Hall]: A slice containing references to examination halls.

students.rs

The students.rs module defines the Student struct, representing individual students in the seat allocation system.

Code Structure

Here’s an overview of the key components and their purposes within students.rs:

Student Struct (Student)

Purpose and Functionality: The Student struct stores information about individual students, including their ID, class, roll number, and subject. It provides methods for creating new student instances and accessing their attributes.

Functions Used

  • Student::new(): Creates a new Student instance by parsing the student’s ID to extract class and roll number.
  • Accessor Methods (id(), class(), roll_no(), subject()): These methods allow users to retrieve specific attributes of a student instance.

halls.rs

The halls.rs module defines the Hall struct, representing examination halls in the seat allocation system.

Code Structure

Here’s an overview of the key components and their purposes within halls.rs:

Hall Struct (Hall)

Purpose and Functionality: The Hall struct represents an examination hall with a specific capacity and a list of students. It allows for adding students to the hall and tracking seat availability.

Functions Used

  • Hall::new(): Creates a new Hall instance with a specified name and capacity.
  • push(): Adds a student to the hall if there is available space. It returns an error if the hall is full.
  • push_empty(): Adds an empty seat to the hall if there is available space. It returns an error if the hall is full.
  • Accessor Methods (name(), students(), is_full(), seats_left(), capacity()): These methods provide access to various hall attributes, such as name, student list, capacity, seat availability, and more.

db.rs

The db.rs module contains functions responsible for database operations, including reading and writing data in the seat allocation system.

Code Structure

Here’s an overview of the key components and their purposes within db.rs:

Reading Halls Table (read_halls_table())

Purpose and Functionality: The read_halls_table() function reads hall information from the database, populates Hall instances, and returns them as a vector. It retrieves data such as hall names and capacities.

Reading Students Table (read_students_table())

Purpose and Functionality: The read_students_table() function reads student information from the database, organizes them by subject, and returns a HashMap that maps subjects to lists of students.

Writing Report Table (write_report_table())

Purpose and Functionality: The write_report_table() function writes the allocation report to the output database using SQL queries. It takes a vector of Hall instances and inserts student allocation data into the report table.

args.rs

  • Purpose and functionality: Manages command-line arguments for the program.
    • Defines the Arguments struct to store argument values.
    • Implements the get function to parse and retrieve command-line arguments.
    • Supports the -r or --randomize flag for specifying randomization of seat allocation.

The pdf Generator

Overview:

This script is responsible for generating PDF reports based on data fetched from a database. It utilizes the FPDF library to create PDF files containing hall allocation information. It generates 3 pdfs, namely -

  1. Halls : It shows the halls occupied by students of various classes, along with their roll numbers.

  2. Packaging: The packaging list provides information about candidates, their classes, subjects, and the number of candidates for each hall.

  3. Seating: It contains the seating arrangement of all the students in that hall.

Table of Contents:

  1. Halls PDF Generation

    1. Data Organization

    2. Data Processing

    3. PDF Generation

  2. Packaging PDF Generation

    1. Data Organization

    2. Data Processing

    3. PDF Generation

  3. Seating Arrangement PDF Generation

    1. Data Organization

    2. Data Processing

    3. PDF Generation

Halls PDF Generation

The “Halls PDF Generation” script is responsible for creating PDF documents that display class allocations to various halls. These PDFs are intended for easy access on notice boards. The script retrieves data from a database and organizes it into the PDF document. The data organization process involves three main steps:

Data Organization

  1. Fetching Data:
  • The script executes an SQL query to retrieve hall and roll number information, sorting the results by hall and class.
  1. Data Structuring:
  • Q_list Q_list contains the fetched data, structured as tuples in the format: (‘class’, ‘hall’, ‘roll_no’).
  1. Initializing PDF List:

  • temp_PDF_list is initialized to temporarily hold data before it is appended to the PDF_list.

  • PDF_list is initialized to hold the lists of roll numbers, in each hall.

Data Processing

  • The script processes the data by checking if the class and hall match the previous record.

  • If they match, the roll number is appended to the current list.

  • If not, the script counts the roll numbers, marks them with the count (e.g., “(15)”), and adds them with the class and hall to temp_PDF_list. Class and hall are updated accordingly.

  • temp_PDF_list is sorted class-wise to ensure organized data.

Example Data:

Consider the following dataset:

[('A','H1',1),('A','H1',2),('A','H2',3), ('A','H2',4),('A','H2',5), ('B','H1',1),('B','H1',2),('B','H1',3),('B','H2',4),('B','H2',5)]

Expected Output:

- Class 'A', Hall 'H1': (1, 2)
- Class 'A', Hall 'H2': (3, 4,5)
- Class 'B', Hall 'H1': (1,2,3)
- Class 'B', Hall 'H2': (4,5)

PDF Generation

The pdf generation involves the following steps:

  • Initialization: Auto page breaks are set. A title, class, date, and session info are centered.

  • Table Creation:

    • A table is created with columns: “Class,” “Hall,” and “Roll No.s.”
    • Roll numbers are formatted and divided into rows if necessary.
    • Class names are displayed once per group.

  • Saving: The PDF is saved with a filename that includes the date and session.

Packaging PDF Generation

The “Packaging List PDF Generation” script creates PDF reports displaying information about candidates, their respective classes, subjects, and the number of candidates for each hall.

Data Organization

The “Packaging PDF Generation” script generates PDF reports displaying candidate information, including their classes, subjects, and the number of candidates for each hall. The process for this script is as follows:

  1. Fetching Data:

    • The script executes SQL queries to retrieve relevant data from the database.
    • The first query retrieves hall, class, subject, and roll number information, sorting the results by hall, class, and subject.
    • The second query counts the number of roll numbers per hall.

  2. Data Structuring:

    • Q_list contains the fetched data, organized as tuples.
    • R_list holds the number of candidates per hall.

  3. Initializing PDF List:

    • PDF_list is initialized as a 2D list with headers.

Data Processing

This section processes the retrieved data and organizes it for inclusion in the PDF.

  • A loop iterates through Q_list.
  • For each record:
    • If the hall, class, and subject match the previous, the roll number is added to the roll_list and sorted.
    • If any of these values change, it signifies a new set of data.
    • The previous data is formatted and added to PDF_list.
    • The variables are updated for the new set of data.
    • The loop ensures that all data is processed.

PDF Generation

The PDF Generation process involves the following steps:

  • Initialization: The script initializes the PDF by setting auto page breaks and key information like the title, Hall number, date, and session are centered on the page.

  • Table Creation:

    • A table is created within the PDF with columns for “Class,” “Subject,” “Roll No.s of Candidates,” “No. of Candidates,” and “Roll No.s of Absentees.”
    • Class and subject names are formatted and split into rows if necessary.
    • Roll number ranges are included in the PDF, and the number of candidates is displayed in the appropriate column.
    • An additional blank column is reserved for displaying the roll numbers of absentees.
    • The PDF also includes important instructions for invigilators.
    • If there are multiple halls, the script generates a new page and repeats the table creation process for each hall.

  • Saving: The resulting PDF is saved with a filename that includes the session information for easy reference.

Seating Arrangement PDF Generation

The “Seating Arrangement PDF Generation” script is responsible for creating PDF documents that display the seating arrangement of students in various halls. The script retrieves data from a database and organizes it into the PDF document. The process involves three main steps:

Data Organization

  1. Fetching Data:

    • The script executes an SQL query to retrieve the hall and class information, then sorting the results by hall.
    • The script executes an SQL query to retrieve hall, seat number, and student ID information, sorting the results by hall and seat number.

  2. Data Structuring:

    • distinct_class contains the query results that has information about hall and class allocations. This list holds unique combinations of hall and class.
    • query_list contains the fetched data, organized as a list of lists, where each inner list represents a record in the format: [hall, seat_no, id].

  3. Initializing Hall List:

    • hall_distinct_list is initialized as a list of lists to group classes by hall.

  4. Grouping Classes by Hall:

    • The script iterates through the distinct_class list (which contains unique hall and class combinations) and groups classes by hall in hall_distinct_list. It also appends seat numbers to each hall’s group.

    Example Data
    [('Hall A', 'Class X'), ('Hall A', 'Class Y'), ('Hall B', 'Class Z')]

    Expected Output
    [['Hall A', 'Class X', 'Class Y'], ['Hall B', 'Class Z']]

Data Processing

The script processes the data to create the seating arrangement:

  • For each hall, the script combines a list of seats and the corresponding student roll numbers.
  • If seat numbers are missing in the data, the script adds them with a placeholder ("-").
  • The script calculates the number of rows required based on the number of seats and divides the seating information into chunks for each row.

PDF Generation

The PDF generation process is as follows:

  • Initialization: Auto page breaks are set, and important information like the title, hall number, date, and session are centered on the page.

  • Class List Table: The script generates a table displaying the list of classes for the hall.

  • Seating Table:

    • The seating information is organized into a table with columns for seat numbers and student roll numbers.
    • Seat numbers are displayed in the “Seat” column, and student roll numbers are displayed in the “Roll No.” column.
    • The script handles page breaks and ensures that the table spans multiple pages if necessary.
    • The script organizes the seating information into tables with appropriate column widths, including seat numbers and roll numbers.

  • Saving: The resulting PDF is saved with a filename that includes the date and session information for easy reference.

The Flutter Component

This component is responsible for creating the user interface (UI) and handling user interactions for the Exam Hall Seat Allocator system. Here’s an overview of the main components and how they work:

Project Structure

  1. bloc/main_screen : This is the entry point of the Flutter application. It initializes the app and sets up the main user interface. It manages the state and logic for the main screen, including handling overlay visibility, opening/closing the drawer, and managing the selected page.

  2. constants/contributordata.dart : This file contains information [name, contributions, GitHub profile link and avatar] of all the contributors to the project.

  3. enums/page_type.dart : This contains the names of various pages in the application, which may be seen in the main application structure.

  4. models:

    • This file defines a Hall class with attributes for a hall’s name and capacity, along with variables to store edited versions of these attributes.

    • It also provides a method to convert an instance of the class into a map for easy storage in to a database.

    • It also defines a contributor class for storing information about the contributors.

  5. service/database: This file sets up a class for working with an SQLite database, initializes the database with a ‘halls’ table (with columns halls and capacity) if it doesn’t exist, and provides a method for fetching data from that table.

  6. widgets/stateless: The files together create and showcase a grid of our contributors, each with an avatar, name, and role. When a contributor is clicked, their GitHub profile URL is launched in a web browser.

  7. hall_page.dart : This file is responsible for managing examination halls. It provides a user interface for users to interact with and manage data related to examination halls.

  8. students_page.dart : This file handles the inputted student data- class, roll number range and subject. It also provides an option to edit the data once entered.

  9. generate_page.dart : This file loads the allocator , to allocate the seats by providing it with the necessary arguments :- The name of the input database and the output database.
    If allocation is successful, then it loads the pdf generator , that generates 3 pdf files - Halls, Packing and the seating arrangement of students. For further info see generator.

  10. manual_edit.dart : It provides a user interface for manual seat allocation editing and PDF generation. Users can select a hall, allocate and deallocate seats, and generate PDF reports.

  11. main.dart : This is the main entry point for the Flutter app, managing navigation, state, and the primary app structure.

Main Application Structure

EHSA’s Flutter component is organized into 3 different pages:

  1. Halls Page
  2. Students Page
  3. Generate Page

here

Halls Page

  • Click here to view the code on the GitHub Repository.

  • Purpose: The halls_page.dart file is a part of the Flutter application responsible for managing examination halls. It provides a user interface for users to interact with and manage data related to examination halls.

  • User Interface Components: The page includes various user interface components, such as text fields for entering hall names and capacities, buttons for adding, editing, and deleting halls, and a data table for displaying hall information.

  • Code Overview :
    - Initially the SQLite Database is initialized and 2 columns - halls and capacity are created. The data entered by the user is then inserted in to the table and is then displayed on the screen.
    - The edit option and delete options perform the respective operations.
    - The Clear Table option deletes the table and clears the screen.

Students Page

  • Click here to view the code on the GitHub Repository.

  • Purpose :The Students Page provides functionalities for managing student data - class, roll list, subject.

  • Actions:

    • Add: Users can add students by specifying their class, subject, and roll numbers individually or in range format (e.g., 101-110).
    • Edit: Existing student data can be modified, including changes to class, subject, and roll numbers.
    • Delete: Unwanted student records can be removed from the database.
    • Clear Table: The entire student database can be cleared.

  • User Interface Components:

    • Table View: Displays a table containing student IDs (in the format of Class - Roll No.) and their respective subjects.
    • Subject View: Lists all subjects currently available in the database.
    • Class View: Shows a breakdown of classes, associated subjects, and roll number lists.

  • Code Overview:

    • Data Processing Functions:

      • expandRanges(String string): Converts range-formatted strings into individual values for roll numbers.
      • convertStringToList(String numbersString): Parses and sorts a comma-separated list of numbers.
      • compareLists(List<int> oldList, List<int> newList): Compares two lists of integers to identify common values, removed values, and added values. Useful for data change detection.

    • Data Submission:

      • trySubmitForm(): Processes and inserts student data into the database based on user input, including class, subjects, and roll numbers. It handles range-based roll numbers as well.

    • Data Retrieval:

      • _fetchTableViewRows(): Retrieves student data from the database for Table View, updating tableViewRows.
      • _fetchSubjectViewRows(): Retrieves subject data from the database for SubjectView, updating subjectViewRows.
      • _subjectListinit(): Initializes the list of subjects from database records. This function is called during initialization.
      • _fetchClassViewRows(): Retrieves class and roll number data from the database for ClassView, updating classViewRows.

    • Data Manipulation:

      • Functions like _updateClassViewRowrollList, _dropTable, _deleteTableViewRow, and _deleteClassViewRow manage data updates and deletions within the database.

    • User Interface Control:

      • addSubjectToSubjectList(): Adds a subject to the list if it doesn’t exist and updates the filtered subjects.
      • nextUnfilledTextField(): Determines the next unfilled text field in the form.
      • onPressEnter(): Handles user interactions when the Enter key is pressed.
      • showClearConfirmationDialog(): Asks for confirmation from the user when clear table button is pressed.

Generate Page

  • Click here to view the code on the GitHub Repository.

  • Purpose: This page is dedicated to generating seat allocation reports [See the various PDF Reports on the Pdf Generator Section].

  • User Interface Components :

    • The session ID is entered in the Session ID Text field.
    • It contains an Enable randomisation check box ,buttons for generating PDFs, manual editing, and viewing generated files.

  • Code Overview:

    • onSubmitSessionId(String input):It validates the input session ID format (DD-MM-YYYY [A/F]N). If valid, updates the _sessionId and stores it in the database. Otherwise, displays an error.

    • The build method constructs the user interface for the Generate page.

    • PDF Generation:

      • The “Generate” button triggers PDF generation using external executables (allocator.exe and pdf_generator.exe) with optional randomization based on the “Enable Randomisation” checkbox.
      • It displays a Snackbar with the result of the PDF generation process.

    • Manual Editing:

      • The “Manual Edit” button navigates to a new screen for making certain specific changes. See Manual Edit.

    • File Viewing:

      • The “View Generated Files” button checks if generated PDF files exist and opens them using the default file handler.
      • The “Open Output Folder” button opens the output folder in the default file explorer.

Manual Edit

The manual edit option is provided for making changes in the allocated seats, by the allocator program.

User Interface

  • Dropdown for Hall Selection

    • Description: Allows the user to select a hall.
    • Functionality:
      • Populates the dropdown with hall names.
      • Updates seat allocation lists when a hall is selected.

  • Seat Allocation Lists

    • Description: Displays seat allocation lists, including unallocated and allocated seats.
    • Functionality:
      • Lists seat allocation records with drag-and-drop functionality.
      • Updates database and UI when seats are allocated or deallocated.

  • Drag-and-Drop Area

    • Description: Provides a drag-and-drop area for transferring seat allocations.
    • Functionality:
      • Accepts transferred seat allocations and updates the UI.
      • Transfers seat allocations back to the unallocated area if needed.

  • Generate PDF Button

    • Description: Initiates PDF generation based on seat allocations.
    • Functionality:
      • Executes an external PDF generation tool.
      • Displays success or failure messages based on the tool’s exit code.

Functions

  • addToDatabase-

    • Description: Adds a seat allocation record to the local database.
    • Parameters: Map<String, dynamic> seat - The seat allocation data to be added.
    • Usage: Called when a seat allocation is dragged and dropped into the allocated area.

  • removeFromDatabase

    • Description: Removes a seat allocation record from the local database.
    • Parameters: Map<String, dynamic> seat - The seat allocation data to be removed.
    • Usage: Called when a seat allocation is dragged back to the unallocated area.

  • updateSeatsList

    • Description: Updates the list of seats with new seat allocation data.
    • Parameters:
      • Map<String, dynamic> transferredItem - The seat allocation data is transferred.
      • bool isReverting - Indicates if the update is due to reverting a drag-and-drop operation.
    • Usage: Called when a seat allocation is transferred or reverted.

  • getHallsInfo

    • Description: Fetches hall information from the local database.
    • Usage: Called during widget initialization to populate the hall selection dropdown.

  • getSeatsInfo

    • Description: Fetches seat allocation data for a selected hall from the local database.
    • Parameters: String hall - The selected hall.
    • Usage: Called when a hall is selected from the dropdown to populate the seat allocation lists.

Page Selection

  • Users can navigate between these pages using the navigation menu in the app.

  • The app maintains the currently selected page, which determines what the user sees.

_selectedPage holds the currently selected page.

Credits Overlay

  • The overlay provides information about the EHSA contributors.
  • The User may visit their GitHub pages by clicking on the tile that shows each contributor’s details.

Summary

This documentation presents a comprehensive overview of the EHSA (Exam Hall Seat Allocator) system, seamlessly integrating Rust, Flutter, and Python components. Rust powers the backend seat allocation algorithm, Flutter provides an intuitive user interface, and Python handles PDF report generation. This synergy creates an efficient and user-friendly solution for managing examination hall seat allocations.

Version History

  • EHSA v2.1 : CLI version, released Dec 20, 2022
  • EHSA v3a : Alpha Version, released June 06, 2023.

Issues and Bug reports

We encourage you to explore EHSA and provide feedback to help us improve and expand this project. To report and issues or bugs, follow the instructions in the readme section in our GitHub Repository!

Click here : EHSA readMe.

Created by protoRes

Clone this wiki locally