QProcess

Purpose

QProcess is a Django and HTMX racing administration and analysis application for the QDB MySQL schema. It is the Python replacement path for the legacy Racing & Sports C# ASP.NET QProcess/admin screens. The application lets an operator select meetings and races, inspect runner and rating data, compare races with historical standards, calculate time figures, generate analysis reports, and perform a small number of controlled QDB updates.

The active application version is 0.11.0. Its primary runtime is QWebHub, where it is mounted at /qprocess/ alongside QDBAdmin and QDG KB Viewer. A standalone Django project remains in the repository for development and fallback use.

Repository: https://github.com/QuantumDataGroup/QProcess

What the program provides

The main interface uses a cascading selection flow:

1. Select date and discipline.
2. Load countries with meetings.
3. Load courses for the chosen context.
4. Load race pills for the meeting.
5. Select a race and lazily load race detail, meeting summary, and runners through HTMX.

The race workspace includes:

• compact race header with course, class, conditions, distance, winner and sectional times, early/late speed, run-on, prize, surface, state of track and FCF;
• editable TAB, Jump, Picnic and FCF values;
• meeting summary with winner, class, FCF, HFA, RTF, race time and sectional time;
• Q Processing and Timeform Ratings runner tables, including historical ratings, dividends, prizes and first-up indicators;
• Times, Times & FCF and Avg Rat analysis tabs;
• TimeFig calculations using course standards and the weight-for-age engine;
• TF Report with sectional/rating calculations and selected write-back actions;
• black-type Q Report with historical instances, lead-up runs, group wins and summary statistics;
• URL restoration through ?race_id=<id> so a selected race can be bookmarked or reloaded.

The application is not purely read-only. Its POST endpoints can update:

• meeting.is_tab;
• race.is_jump, race.is_picnic_race and race.fcf;
• run.timeform_symbol;
• run.time_ratingp.

These operations use server-side field whitelisting where applicable. The current deployment is intended as a trusted local administration tool; authentication remains deferred and several write endpoints are CSRF-exempt. It must not be exposed as a public web application without an explicit authentication, authorization and CSRF review.

Technology and design

• Web framework: Django 6.0.x (Django>=6.0,<6.1).
• Frontend: server-rendered templates, HTMX and Bootstrap; no JavaScript framework or frontend build step.
• Database: QDB MySQL through PyMySQL.
• Data access: raw SQL through Django database cursors; the legacy business schema is not managed by Django ORM migrations.
• Static design system: shared QDB styling from Global Memory/CSS, plus QProcess-specific assets.
• Version source: qprocess_racing/versioning.py.

Raw SQL is deliberate: QDB is a pre-existing schema owned by the wider data platform, and QProcess needs precise control over legacy query shapes. The trade-off is schema-drift risk. Version 0.11.0 therefore established a live information_schema audit as the reliable way to validate table and column references.

Current schema names verified for the live application include:

• course (singular), not the historical courses name;
• run.beaten_margin, not run.margin;
• meeting.is_prelocked, not meeting.is_pre_locked;
• race.rmeeting_id for the race-to-meeting relationship;
• race.time_winner_sec as the reliable winner-time value;
• race.distance_val as the metres value;
• country.hemisphere for WFA hemisphere selection.

Some older repository documents describe the pre-v0.11 schema or the former apps/racing package. For current behavior, prefer handover/HANDOVER-0.11.0.md, changelog/CHANGELOG-0.11.0.md, qprocess_racing/urls.py, qprocess_racing/views.py, and the live QWebHub registry.

Runtime architecture

QWebHub is the primary owner of the Django process. It supplies the shared virtual environment, settings, middleware, database aliases, template search paths, static-file collection and root URL routing. QProcess supplies its application package, URL configuration, raw-SQL views, calculations, templates and static assets.

Browser
  |
  v
QWebHub WSGI application
  |-- shared Django 6.0 environment
  |-- shared middleware, templates and static collection
  |-- DATABASES[default] -> qdb
  |-- DATABASES[qdgwiki] -> qdgwiki
  |
  +-- /qdbadmin/       -> qdbadmin_core
  +-- /qprocess/       -> qprocess_racing
  +-- /knowledge-base/ -> qdgkb_viewer

qwebhub/modules.py resolves each module beneath PROJECTS_ROOT and adds the enabled project roots to Python's import path. QProcess is therefore imported directly from its existing directory; it is not copied into QWebHub when the server starts.

The primary local startup path is:

C:\Users\Robert\Projects\QWebHub\start_server.bat

The launcher creates or reuses QWebHub\.venv, installs the hub and enabled-module requirements into that one environment, applies Django bookkeeping migrations, runs collectstatic, runs manage.py check, opens the hub, and starts Django's development server on port 8000.

Current local URLs:

• Hub: http://127.0.0.1:8000/
• QProcess: http://127.0.0.1:8000/qprocess/
• QDBAdmin: http://127.0.0.1:8000/qdbadmin/
• QDG KB Viewer: http://127.0.0.1:8000/knowledge-base/
• Health endpoint: http://127.0.0.1:8000/healthz/

The current launcher still uses Django runserver; a production-style local Windows service/Waitress host has been discussed but is not yet implemented in the reviewed source.

QWebHub and QProcess directory structure

The cross-project layout matters because QWebHub imports sibling projects through its module registry.

C:\Users\Robert\Projects\
|-- QWebHub\
|   |-- .venv\                       generated shared Python environment
|   |-- manage.py                    hub Django entry point
|   |-- start_server.bat             local all-module launcher
|   |-- bootstrap.py                 installs enabled module requirements
|   |-- requirements.txt             hub dependencies and Django constraint
|   |-- qwebhub\
|   |   |-- modules.py               registry and PROJECTS_ROOT resolution
|   |   |-- settings.py              shared Django settings and DB aliases
|   |   |-- config.py                canonical DB/static/template configuration
|   |   |-- urls.py                  registry-driven root URL mounting
|   |   |-- wsgi.py                  current server entry point
|   |   |-- asgi.py                  Django ASGI entry point/future integration
|   |   |-- context_processors.py    hub version context
|   |   `-- hub_version.py           hub version source
|   |-- core\
|   |   |-- views.py                 landing page and health response
|   |   |-- urls.py
|   |   `-- templates\hub\           namespaced hub templates
|   |-- staticfiles\                 generated collectstatic output
|   |-- scripts\ftp_deploy.py        historical deployment helper
|   |-- changelog\ and handover\     QWebHub release history
|   `-- NEW_MODULE.md / harness.md    module guidance and original design
|
|-- QProcess\
|   |-- manage.py                    standalone Django entry point
|   |-- requirements.txt             Django/PyMySQL module requirements
|   |-- qprocess\
|   |   |-- settings.py              standalone settings only
|   |   |-- urls.py                  standalone `/qprocess/` mount
|   |   |-- wsgi.py
|   |   `-- asgi.py
|   |-- qprocess_racing\             active Django application package
|   |   |-- views.py                 live raw-SQL views and write endpoints
|   |   |-- urls.py                  application route table
|   |   |-- race_calcs.py            WFA and FCF/WHFA calculations
|   |   |-- context_processors.py    version badge context
|   |   |-- versioning.py            authoritative QProcess version
|   |   |-- apps.py / admin.py / models.py / tests.py
|   |   |-- migrations\              package marker; business schema unmanaged
|   |   `-- static\racing\           app-specific CSS/image assets
|   |-- templates\
|   |   |-- base.html                legacy/shared standalone base
|   |   `-- racing\
|   |       |-- base.html            active QProcess base template
|   |       |-- index.html           filters, calendar, race workspace/actions
|   |       |-- tf_report.html       standalone TF Report
|   |       |-- qreport.html         standalone Q Report
|   |       `-- partials\             HTMX country/course/race/detail panels
|   |-- reference_builder\           standalone standards ETL program
|   |   |-- ref_builder.py           CLI and orchestration
|   |   |-- builders.py              validation, aggregation and bulk upsert
|   |   |-- schema.py                reference-table DDL
|   |   |-- build_log.py             build/audit records
|   |   |-- db.py                    independent QDB connection helper
|   |   |-- race_calcs.py            shared WFA/outlier calculations
|   |   `-- SPEC.md / HANDOVER.md / CHANGELOG.md / newtables.md
|   |-- changelog\                   QProcess release history
|   |-- handover\                    release orientation and watch lists
|   |-- scripts\ftp_deploy.py        historical module deployment helper
|   |-- ARCHITECTURE.md              detailed but partly pre-v0.11 reference
|   |-- move_config.md               QWebHub integration design/history
|   `-- CLEANUP.md                   obsolete/dead-file notes
|
|-- AdminManagement\QDBAdmin\        sibling QWebHub module
|-- QDG KB Viewer\                   sibling QWebHub module
`-- Global Memory\CSS\               shared QDB design system

URL surface

All QProcess application routes are relative to /qprocess/:

Relative route	Purpose
/	Main QProcess interface
countries/, courses/, races/	HTMX selection cascade
race/<id>/	Race detail shell
race/<id>/summary/	Meeting summary
race/<id>/runners/	Q Processing and Timeform runner tables
race/<id>/times/	Meeting times and standards
race/<id>/times-fcf/	Class/course FCF comparison
race/<id>/avg-rat/	Historical winner-rating statistics
race/<id>/fcf/	FCF recalculation panel
timefig/	Time Figure modal
tf-report/	TF Report
q-report/	Black-type Q Report
race-ctx/	Restore date/discipline/course context from race ID
update-flag/	Whitelisted TAB/Jump/Picnic/FCF updates
update-tf-symbol/	Timeform symbol update
update-trat-plus/	TRat+ update

Reference-table builder

reference_builder is independent of Django and is not mounted in QWebHub. It derives historical norms from QDB and writes the reference_* tables consumed by QProcess.

Its central rules are:

• validate candidate races individually before aggregation;
• reject or quarantine physically implausible times rather than allowing them to skew standards;
• keep an audit log and per-row issue records;
• distinguish course, distance, surface, state-of-track group and discipline;
• use race.time_winner_sec, never unreliable sentinel-style race.time_winner values;
• preserve the legacy standard-deviation behavior by default for compatibility, while allowing true standard deviation mode;
• bulk-upsert generated standards and support one-course, all-course and dry-run workflows.

Key outputs include reference_avg_time, reference_course_time, reference_class_quality, reference_course_quality, optional reference_avg_rating, and the build/issue audit tables. The WFA grid is implemented as pure Python rather than a database table.

Current status and limitations

• Version 0.11.0 was live-verified through QWebHub for the selection cascade and race-detail browsing path.
• The QProcess raw SQL in active views.py was audited against live information_schema after schema-drift failures were found.
• TF Report, Q Report, TimeFig, FCF and other write-back actions were not all re-tested in that v0.11.0 live-verification session.
• qprocess_racing/views_full.py is dead code and still contains historical schema names; it must not be wired back without correction or deletion.
• The Sectionals feature remains unimplemented.
• The reference builder is a separate program and was not included in the v0.11.0 active-view schema audit.
• Some early documents and builder descriptions use historical table names such as courses; validate current SQL against live schema before changing or rerunning old code.
• Hub authentication is deferred. Treat the system as a trusted local admin tool.

Recommended starting points

For current work, read in this order:

1. handover/HANDOVER-0.11.0.md
2. changelog/CHANGELOG-0.11.0.md
3. qprocess_racing/urls.py
4. qprocess_racing/views.py
5. qprocess_racing/race_calcs.py
6. QWebHub/qwebhub/modules.py
7. QWebHub/qwebhub/settings.py
8. move_config.md for integration history
9. ARCHITECTURE.md for broader context, correcting it with v0.11.0 facts
10. reference_builder/HANDOVER.md when working on standards generation