Reference and notes

Repository map

app/                    Python workflow, rules, storage, email, and templates
public/                 Azure Static Web Apps browser client
function_app.py         Hourly timer registration
host.json               Functions host configuration
requirements.in         Direct runtime dependencies
requirements.txt        Hash-locked runtime graph used by Azure remote build
requirements-dev.*      Direct and locked test environment
ci/                     Pinned tools, lock updater, SBOM and docs helpers
docs/                   Documentation Markdown and stylesheet
ci/docs/                Starlight configuration, components, and npm lockfile
tests/                  Mocked application and SBOM checks
scripts/preview_emails.py Local sample HTML and plain-text email generation
.gitlab-ci.yml          Validation, Azure deployment, Pages publication

Generated output and environments are ignored: docs-site/, .docs-venv/, .ci-tools/, SBOM environments, reports, caches, and node_modules/. local.settings.json is also ignored.

Important implementation notes

Topic	Current behavior
Hosting	Website on Static Web Apps; JSON on Blob Storage; docs on GitLab Pages
API	The Function registers a timer only; it has no public HTTP endpoint
Refresh	The browser fetches JSON on load; its minute timer only updates the effective week
Notification timing	Halftime and final messages are sent after the game is final
BYE	Displayed on the site; no scheduled BYE postgame email
Delivery guarantees	Conditional send claims avoid common duplicates; ambiguous sends need review
History	One overwritten snapshot per UTC day, not an immutable event log
Payouts	Earned prizes, not a payment ledger
Scores	External ESPN responses are validated conservatively; missing values are not zeroes
Tests	Python and Playwright browser regression tests mock external calls; they are not a live Azure smoke test
Hosting changes	Confirm the live Python version and plan before changing deployment settings

Security and supply-chain boundaries

The Python SBOMs cover resolved runtime and test packages. They do not inventory OS packages, CI tools, or CDN-loaded frontend assets. Grype blocks High/Critical findings under the current policy; a Medium finding remains visible for review. Biome provides web lint checks, and Bandit scans Python source. These checks are not a guarantee that production is free of vulnerabilities.

The documentation bundles Mermaid from its npm lockfile and serves it locally. Application secrets remain in Azure/GitLab settings; public snapshots contain display data only. Changing the public snapshot shape should include a review of what fields become publicly visible.

Follow-up opportunities

These are possible future improvements, not capabilities already implemented:

• Read-only post-deployment smoke checks for the website and Function workflow.
• Scheduled vulnerability scans, with explicit deployment-source rules first.
• An image-size budget for public/.
• A reviewed migration from Linux Consumption to Flex Consumption.
• Automated, reviewed updates for tool versions, image digests, and dependency locks.

Primary references

• GitLab Pages
• GitLab CI/CD configuration
• GitLab Azure workload identity
• Azure Functions Python build options
• Azure Functions app settings
• Azure Storage website and Blob endpoint behavior
• Starlight documentation
• Syft

These guides describe the repository’s implementation. Azure/GitLab account configuration may differ and should be checked in the respective service when troubleshooting a live deployment.