Q-STAR is a production-grade, offline-first desktop application designed for educational institutions operating in low-connectivity environments. Built using a modular backend architecture inspired by NestJS principles and paired with a modern Vanilla JavaScript Single Page Application (SPA), Q-STAR provides secure, high-throughput attendance logging using native hardware QR scanning.
- Ray Emanuele P. Untal — Core Backend Architect & Security Engineer
- Raphael Khandie B. Bihag — Data Science & Frontend Integration Engineer
Q-STAR follows a strict separation of concerns, isolating application logic from persistent data storage. This design enables application updates without risking historical attendance records, user configurations, or audit logs.
C:/QSTAR/
├── Data/ <-- Persistent Storage (Untouched during updates)
│ ├── logs <-- Rotating application logs
│ ├── attendance.db <-- Normalized SQLite database
│ └── config.json <-- Application configuration & scrypt-hashed credentials
│
└── Application/ <-- Application Layer (Updated when new versions are installed)
├── launcher.py <-- Update checker and bootstrapper
├── main.py <-- Primary application entry point
├── version.json <-- Semantic version tracking
├── core/ <-- Shared infrastructure components
├── modules/ <-- Feature-bounded domain modules
└── web/ <-- Vanilla JS SPA frontend
Migrated from the legacy Eel framework to pywebview, leveraging native operating system web rendering engines while maintaining a desktop-native experience.
Transitioned from a flat-file persistence model to a fully normalized SQLite relational schema supporting centralized student, faculty, and attendance records through foreign key relationships.
Administrative credentials are secured using the scrypt key derivation algorithm rather than plaintext storage.
Implemented automated rotating log management using Python's RotatingFileHandler, preventing uncontrolled log growth while preserving historical diagnostic information.
The backend is divided into feature-bounded domains such as:
- Attendance
- Authentication
- Dashboard
- Faculty
- Student
- User Management
Each domain follows a structured architecture:
Exposes application functionality through the pywebview JavaScript bridge.
Contains business logic, validation workflows, and application rules.
Acts as a lightweight DTO-style layer for data validation and consistency.
Handles transactional database operations through a centralized database context.
Q-STAR v2.0 replaces fragile regular-expression-heavy parsing with a deterministic structural validation engine.
Supported identifiers follow a structured format:
XX-YY-ZZ
The number of characters within each segment may vary, but the dash-separated structure is required.
Classification is performed using the contents of the identifier:
- Identifiers containing only numeric values are automatically classified as Students.
- Identifiers containing one or more alphabetic characters are automatically classified as Faculty or Staff.
- Malformed, invalid, or non-conforming values are intercepted during validation and safely ignored before processing.
This approach remains reliable regardless of segment lengths while reducing false positives caused by pattern-specific parsing.
Upon startup, the launcher performs a check against the GitHub Releases API.
If a newer semantic version is available:
- The user is notified through a custom application modal.
- The updated application package is downloaded.
- The application layer is replaced while preserving the data layer.
- The system automatically relaunches into the updated version.
This process ensures seamless upgrades without affecting attendance records, logs, or application settings.
The user interface operates as a Single Page Application (SPA) built using native browser technologies.
Views and reusable UI segments are implemented using custom HTMLElement components, providing modularity without introducing heavyweight frontend frameworks.
- Python 3.10+
- Compatible camera device
- Windows environment (recommended for production builds)
git clone https://github.com/HorizUntall/QSTAR.git
cd qstar-attendancepip install -r requirements.txtWhen running or building manually, ensure the following files are present:
libiconv.dll
libzbar-64.dll
These libraries are required for QR code decoding through pyzbar.
python main.pypython launcher.pyThe launcher should be used when testing version-checking and update workflows.
Q-STAR uses Auto Py to Exe as the official packaging workflow.
Two separate executables are generated:
This executable contains the primary application runtime and is generated from:
main.py
Script Location
main.py
Packaging Mode
One Directory
Console Window
Window Based (Hide Console)
Optional Icon
web/assets/images/
Additional Files
web/
libiconv.dll
libzbar-64.dll
version.json
QSTAR_Engine.exe
_internal/
This executable is generated from:
launcher.py
Script Location
launcher.py
Packaging Mode
One File
Console Window
Window Based (Hide Console)
Optional Icon
web/assets/images/
After both executables have been built, the launcher must be placed alongside the application runtime:
launcher.exe
QSTAR_Engine.exe
_internal/
The naming and folder structure above are required because the launcher is responsible for detecting updates and launching the application runtime correctly.
One of the primary design goals of Q-STAR is update-safe persistence.
Application updates only replace executable assets and application code while preserving:
- Attendance records
- User accounts
- Faculty records
- Student records
- Configuration files
- Historical logs
This ensures institutions can deploy updates without risking operational data loss.