ovladisluvv/gradetrack

Purpose and entry points

GradeTrack is a Python 3.12 desktop application for MSU students. It authenticates against lk.msu.ru, retrieves grade HTML, calculates averages, and evaluates whether an honors diploma is reachable. GUI startup is src/gui/app.py (python -m gui.app from src); packaged startup is defined by GradeTrack.spec.

Layered application boundary

The repository uses a deliberate downward dependency structure: GUI orchestrates services; services combine web I/O with pure core logic; core does not perform network I/O. Package boundaries are represented by:

• src/gui/__init__.py

• src/services/__init__.py

• src/core/__init__.py

This separation permits analysis of saved HTML without network access and keeps portal-specific behavior out of grading rules.

Portal access and scraping

src/web owns the authenticated HTTP session with the external MSU personal-account service. Authentication obtains CSRF state and submits credentials; failures become typed domain exceptions. Scraping returns raw grades-page HTML only, leaving its interpretation to core.

• src/web/auth.py

• src/web/scraper.py

• src/web/exceptions.py

The material external dependency is lk.msu.ru; its authentication flow and page markup are integration boundaries prone to upstream change.

Grade ingestion and normalization

Core converts fetched or saved HTML into structured grade records, then filters unusable/unpassed entries and maps textual grades to numeric values. During preprocessing, each record is also classified as diploma-relevant.

• src/core/parser.py

• src/core/preprocessor.py

• src/core/grade_models.py

Flow: HTML → GradeInfo-style models → normalized numeric grades plus in_diploma classification. This is the principal boundary between unstable portal markup and stable analytical inputs.

Diploma curriculum data

Diploma inclusion is data-driven rather than hard-coded. The selector resolves subject lists by faculty, program, department, and semester; early semesters use program-level files, while later semesters can use department-specific lists.

• src/core/diploma_subjects.py

• data/in_diploma/vmk/fiit/sem1.txt

• data/in_diploma/vmk/pmi/ani/sem5.txt

The provided curriculum coverage makes honors-diploma analysis materially targeted at VMK bachelor programs. University-selection structure is supplied separately through data/university_structure.yaml.

Analysis and service orchestration

The analyzer calculates averages with and without retake penalties, optional semester ranges, diploma-grade distribution, and honors-diploma reachability. grades_service is the application-facing facade: one path runs scrape-to-analysis, another accepts preexisting HTML.

• src/core/analyzer.py

• src/services/grades_service.py

• data/test_grades.html

Control flow is GUI/user choices → service → authenticated scrape (or saved HTML) → parse/preprocess/curriculum tagging → analysis result → GUI rendering.

Desktop runtime, state, and delivery

PyQt6 provides the only user interface: a terminal-styled wizard collects credentials and academic selections, maintains navigation/session state, and moves blocking portal work to a background thread. Configuration and data paths support both source and PyInstaller execution.

• src/gui/state_manager.py

• src/gui/wizard_view.py

• src/gui/terminal_view.py

Deployment supports native PyInstaller binaries and Dockerized GUI execution with X11/OpenGL. Docker mounts config and data, so those are runtime-editable inputs; image publishing and releases are automated via .github/workflows/docker-publish.yml and .github/workflows/release.yml.