🗄 Student Archive — v3.0.0

A modern, production-grade Student Information & Grade Management System
built with Python 3 + PyQt5.

---

✨ What's New in v3

Area	Original (v1–v2)	v3 (This Version)
Architecture	Monolithic single file, spaghetti UI logic	Layered: core/, ui/, utils/, tests/
Database	Raw SQL string concatenation (SQL injection risk)	Parameterized queries, WAL mode, indexes, triggers
Auth	Plain-text password comparison	SHA-256 hashing
UI layout	Absolute pixel positioning	Proper layout managers, responsive sizing
Forms	Duplicate add/edit/delete logic per page	Single FormDialog reused for both add & edit
Image handling	os.startfile() (Windows-only)	Cross-platform subprocess viewer
Search	None / broken	Full-text search across all relevant columns
Statistics	None	New Analytics page with bar charts + top students
Code duplication	QMessageBox.setStyleSheet() repeated 30+ times	show_message() helper, one place to change
Tests	None	30+ pytest unit tests covering DB + validators
Documentation	None	This README + in-code docstrings throughout

---

📁 Project Structure

Student_archive/
├── main.py                    # Entry point
├── requirements.txt
├── README.md
│
├── core/
│   ├── __init__.py
│   └── database.py            # All DB logic — parameterized, context-managed
│
├── ui/
│   ├── __init__.py
│   ├── theme.py               # Design system: colors, fonts, global QSS
│   ├── widgets.py             # Reusable components (StatCard, SearchBar, Table, …)
│   ├── login_window.py        # Frameless dark login screen
│   ├── main_window.py         # App shell: sidebar + stacked pages
│   └── pages/
│       ├── __init__.py
│       ├── students_page.py   # Students CRUD + detail panel
│       ├── grades_page.py     # Grades CRUD
│       └── stats_page.py      # Analytics dashboard
│
├── utils/
│   ├── __init__.py
│   └── validators.py          # Email, phone, age, required-field validators
│
├── data/                      # Auto-created at runtime
│   ├── Student_archive.db
│   └── admin.db
│
└── tests/
    ├── __init__.py
    └── test_database.py       # 30+ unit tests for core layer

---

🚀 Quick Start

Prerequisites

• Python 3.9+
• pip

Installation

# Clone the repository
git clone https://github.com/alanhasn/StudentSimpleArchive-Desktop-App-Using-PyQt5-Modern.git
cd StudentSimpleArchive-Desktop-App-Using-PyQt5-Modern

# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate    # Linux/macOS
venv\Scripts\activate       # Windows

# Install dependencies
pip install -r requirements.txt

# Run the application
python main.py

Default Login

Field	Value
Username	admin
Password	admin123

⚠️ Change the default password immediately after first login.
A future release will prompt for this on first run.

---

🗃 Database Schema

students table

Column	Type	Notes
id	INTEGER PK	Auto-increment
name	TEXT	Required
last_name	TEXT	Required
email	TEXT UNIQUE	Optional, validated
phone_number	TEXT	Optional
country, city, region	TEXT	Optional
age, birthday	TEXT	Optional
gender, health, study, martial_status	TEXT	Enum-constrained in UI
native_language, mother_name, father_name	TEXT	Optional
image_data	TEXT	Base64-encoded photo
created_at, updated_at	DATETIME	Auto-managed via trigger

student_grades table

Column	Type	Notes
id	INTEGER PK	Auto-increment
student_id	INTEGER	FK → students(id) ON DELETE CASCADE
name, last_name	TEXT	Denormalized for display convenience
math_score, english_score, python_score, …	TEXT	Score or label

admin_data table (in admin.db)

Column	Type	Notes
id	INTEGER PK
username	TEXT UNIQUE
password	TEXT	SHA-256 hash

---

🔒 Security Notes

1. Parameterized queries — all SQL uses ? placeholders; no string formatting in queries.
2. Password hashing — admin passwords are stored as SHA-256 hashes, never plain text.
3. Input validation — email format, required fields, and age range are validated before any DB write.
4. Foreign keys — PRAGMA foreign_keys = ON enforced per connection.
5. WAL mode — SQLite Write-Ahead Logging enabled for better concurrency safety.

For a production deployment, upgrade password hashing from SHA-256 to bcrypt or argon2:

pip install bcrypt

Then replace _hash_password() in core/database.py.

---

🧪 Running Tests

# From the project root
python -m pytest tests/ -v

# With coverage
pip install pytest-cov
python -m pytest tests/ --cov=core --cov=utils --cov-report=term-missing

Expected output: 30+ tests passing covering auth, CRUD, search, stats, and validators.

---

🖥 UI Overview

Login Screen

• Frameless dark window, draggable
• Inline error feedback (no dialog popups for wrong password)
• Keyboard shortcut: Enter to submit

Main Application

• Sidebar navigation — Students / Grades / Statistics
• Students page — searchable table + right-side detail panel with photo, edit, delete
• Grades page — searchable table with per-subject score management
• Statistics page — summary cards, country/gender bar charts, subject progress bars, top-5 leaderboard

---

🛠 Architecture Decisions

Why DatabaseManager as a service class?

The original code called sqlite3.connect("archive.db") in dozens of UI event handlers. This meant:

• Connection lifecycle unmanaged (connections never closed properly)
• SQL injection surface spread across 30+ locations
• No single place to add logging, error handling, or migration logic

DatabaseManager consolidates all of this behind a context-managed connection (@contextmanager) and exposes typed methods that return plain Python dicts — the UI layer never sees a sqlite3.Row object.

Why a single FormDialog for add + edit?

The original had separate save_button(), change(), update_item(), and clean_fields() functions that duplicated ~80% of the same widget creation and validation code. A single StudentFormDialog(existing=None) handles both paths cleanly.

Why GLOBAL_QSS in theme.py?

Qt stylesheets applied per-widget with inline strings create maintenance nightmares — changing a border radius means hunting through 50 files. A single stylesheet applied at QApplication level cascades to all children, and the design token variables (colors, font sizes) are defined once.

---

📋 Environment Variables

The application currently reads no environment variables — paths are relative to the project root. For a server deployment, these would be externalized:

Variable	Default	Description
SIMORX_DB_PATH	data/simorx_archive.db	Path to main database
SIMORX_ADMIN_DB_PATH	data/admin.db	Path to admin credentials DB
SIMORX_LOG_LEVEL	INFO	Python logging level

---

🚢 Deployment

Desktop (standalone)

Use PyInstaller to create a single executable:

pip install pyinstaller
pyinstaller --onefile --windowed --name "StudentArchive" main.py

The dist/StudentArchive executable will include Python and all dependencies. The data/ folder should be distributed alongside it (or created on first run, which already happens automatically).

---

👥 Team

Role	Person
Project Manager	Vorsynth
Development Lead	Vorsynth

---

📝 Changelog

v3.0.0 (Modernization)

• Complete architecture overhaul: layered core / ui / utils / tests
• SQL injection vulnerabilities patched — all queries parameterized
• Hashed password storage (SHA-256)
• Modern QSS design system with sidebar navigation
• Statistics dashboard (new)
• 30+ unit tests (new)
• Cross-platform photo viewer
• Reusable form dialogs eliminating code duplication
• Full README and docstrings

v2.x (Legacy)

• Original monolithic implementation
• Basic CRUD with raw SQL string formatting
• Absolute-positioned widgets
• No tests, no documentation