The Score Processing Pipeline in Athena is a multi-layered system responsible for handling score submissions, primarily focusing on maintaining compatibility with the stable osu! client binary protocol and legacy web endpoints. It orchestrates the flow from raw multipart form data intake to final persistence, performance (PP) calculation, and leaderboard updates.

The pipeline is split between an immediate response phase (intake, authorization, and initial persistence) handled by the main application process, and a heavy-processing phase (PP calculation and projection refreshes) handled by background workers. This separation ensures the client receives a timely response while durable consistency and intensive calculations are processed asynchronously.
Sources: AGENTS.md:389-392, src/osu_server/services/commands/scores/process_submission.py:348-356

Pipeline Orchestration

The orchestration logic is centralized in the ProcessScoreSubmissionUseCase. It follows a strict sequence of operations to ensure data integrity and idempotency.

Submission Workflow Stages

The pipeline follows these fixed steps:

Fingerprint Generation: Creates a unique SHA-256 hash based on user ID, beatmap checksum, client timestamp, and request hash to identify retries and prevent duplicate processing.
Authorization: Validates credentials (password MD5) and active session status.
Beatmap Eligibility: Checks if the beatmap exists and if its status (Ranked, Loved, etc.) accepts score submissions.
Validation: Verifies hit counts and identifies discrepancies between client-reported grades and server-calculated grades.
Replay Storage: Persists the replay binary to a blob storage provider.
Persistence: Records the score in the database and updates personal bests.
Performance Calculation: Triggers an asynchronous request for PP calculation.

Sources: src/osu_server/services/commands/scores/process_submission.py:365-375, src/osu_server/services/commands/scores/process_submission.py:378-406

Workflow Sequence Diagram

This diagram illustrates the interaction between the transport layer, the command use-case, and supporting infrastructure services.

Generating architecture diagram...

Sources: src/osu_server/services/commands/scores/process_submission.py:378-406, tests/integration/test_score_submission_integration.py:301-344

Data Mapping and Decoding

Because the pipeline supports legacy stable clients, it must decode encrypted multipart form data into internal domain models. This is handled by the StableScoreSubmitDecoder.

Request Materials

The transport layer first extracts raw materials into a StableScoreSubmitRequestMapping. This structure holds the encrypted payload, IV, and various client metadata fields such as osuver and ft (fail time).

Field	Description
`encrypted_payload`	The colon-delimited score string, encrypted by the client.
`iv`	The Initialization Vector provided by the client for decryption.
`password_md5`	Normalized MD5 hex of the user's password.
`submission_metadata`	Opaque fields (e.g., tokens, `bmk`, `sbk`) hashed for diagnostics.

Sources: src/osu_server/transports/stable/web_legacy/mappers/score_submit.py:165-190, src/athena_cli/stable_verification/score_submit.py:27-38

Decryption and Parsing

The StableScoreSubmitDecoder uses a StableScorePayloadDecryptor to produce plaintext. The StableScorePayloadParser then converts this plaintext (which can be a 16-field legacy or 16-19 field stable format) into a ParsedScore.
Sources: src/osu_server/transports/stable/web_legacy/mappers/score_submit.py:108-132, src/osu_server/transports/stable/web_legacy/mappers/score_submit.py:284-307

Performance Calculation Pipeline

PP calculation is an asynchronous process triggered after initial score persistence. It is managed by background workers using taskiq.

Performance Execution Flow

When a worker picks up a calculation job, it follows the ExecutePerformanceCalculationUseCase.

Generating architecture diagram...

Sources: tests/unit/services/commands/scores/performance/test_execute_calculation.py:127-148, AGENTS.md:389-392

Calculation States

Calculations transition through several states to handle retries and failures:

QUEUED: Initial state after the command process requests calculation.
FETCHING_FILE: Worker is retrieving the beatmap metadata or file.
CALCULATING: Worker is running the rosu-pp-py adapter.
COMPLETED: PP and Star Rating successfully calculated and stored.
UNAVAILABLE: Permanent failure (e.g., beatmap unparseable or score data invalid).

Sources: tests/unit/services/commands/scores/performance/test_execute_calculation.py:263-289, tests/unit/services/commands/scores/performance/test_execute_calculation.py:309-340

Leaderboard Projection Reconciliation

Athena uses projections for leaderboards to ensure fast read performance. The pipeline handles two types of reconciliation:

Immediate Update: When a score is submitted, upsert_if_better is called to potentially update the beatmap_leaderboard_user_bests table.
Rebuild/Refresh: If a replacement PP calculation results in a lower PP value than the previous calculation (e.g., due to a calculator version update), the system triggers a rebuild of the user's slice to find the next best score.

Sources: tests/unit/services/commands/scores/performance/test_projection_refresh.py:30-58, tests/unit/services/commands/scores/performance/test_execute_calculation.py:192-225

Response Formatting

The pipeline concludes by mapping the SubmissionResult back to the stable client's expected text format, which includes beatmap metadata, beatmap-specific charts, and overall player charts.

Stable Chart Fields

Chart Type	Key Fields
Beatmap	`rankBefore`, `rankAfter`, `accuracyBefore`, `ppBefore`, `onlineScoreId`
Overall	`totalScoreBefore`, `rankedScoreAfter`, `ppAfter`, `achievements-new`

Sources: src/athena_cli/stable_verification/score_submit.py:40-62, src/osu_server/transports/stable/web_legacy/mappers/score_submit.py:469-509

Conclusion

The Score Processing Pipeline is a critical system that balances legacy compatibility with modern architectural standards. By utilizing a clear separation between immediate intake and background processing, and by strictly enforcing state transitions through use-cases and the Unit of Work pattern, Athena maintains a robust and scalable scoring infrastructure.
Sources: AGENTS.md:104-106, src/osu_server/services/commands/scores/process_submission.py:348-356

Resources

AI code review
Bug Bench
AI coding statistics
Coding standards
Agents
Wikis

View on GitHub

Back to directory

Repository

Reticulmz/athena

Overview

Athena Project Overview

System Architecture

Modular Monolith Architecture Dependency Injection with Dishka

Core Features

Beatmap Management Chat and Messaging BanchoBot and Commands Identity, Auth, and Relationships Score Processing Pipeline Performance Points Engine Leaderboards and Stats Projections

Data Management/Flow

Relational Persistence (PostgreSQL)Blob Object Storage State, Cache, and Queues (Valkey)

Backend Systems

Bancho Binary Protocol Implementation Legacy Web PHP Adapters Lazer and Public APIs Background Workers and Tasks Rust Cryptography Extension Domain Events and Messaging

Extensibility and Customization

Athena CLI Tooling Stable Compatibility Verifier Coding Agent Rules and Guidelines

Deployment/Infrastructure

Environment Setup and Run Test Strategy and Fixtures Quality Gates and CI

Score Processing Pipeline

Relevant source files

The following files were used as context for generating this wiki page:

src/osu_server/services/commands/scores/process_submission.py
src/osu_server/transports/stable/web_legacy/mappers/score_submit.py
src/athena_cli/stable_verification/score_submit.py
tests/integration/test_score_submission_integration.py
tests/unit/services/commands/scores/performance/test_execute_calculation.py
AGENTS.md

Pipeline Orchestration

The orchestration logic is centralized in the ProcessScoreSubmissionUseCase. It follows a strict sequence of operations to ensure data integrity and idempotency.

Submission Workflow Stages

The pipeline follows these fixed steps:

Fingerprint Generation: Creates a unique SHA-256 hash based on user ID, beatmap checksum, client timestamp, and request hash to identify retries and prevent duplicate processing.
Authorization: Validates credentials (password MD5) and active session status.
Beatmap Eligibility: Checks if the beatmap exists and if its status (Ranked, Loved, etc.) accepts score submissions.
Validation: Verifies hit counts and identifies discrepancies between client-reported grades and server-calculated grades.
Replay Storage: Persists the replay binary to a blob storage provider.
Persistence: Records the score in the database and updates personal bests.
Performance Calculation: Triggers an asynchronous request for PP calculation.

Sources: src/osu_server/services/commands/scores/process_submission.py:365-375, src/osu_server/services/commands/scores/process_submission.py:378-406

Workflow Sequence Diagram

This diagram illustrates the interaction between the transport layer, the command use-case, and supporting infrastructure services.

Generating architecture diagram...

Sources: src/osu_server/services/commands/scores/process_submission.py:378-406, tests/integration/test_score_submission_integration.py:301-344

Data Mapping and Decoding

Because the pipeline supports legacy stable clients, it must decode encrypted multipart form data into internal domain models. This is handled by the StableScoreSubmitDecoder.

Request Materials

Field	Description
`encrypted_payload`	The colon-delimited score string, encrypted by the client.
`iv`	The Initialization Vector provided by the client for decryption.
`password_md5`	Normalized MD5 hex of the user's password.
`submission_metadata`	Opaque fields (e.g., tokens, `bmk`, `sbk`) hashed for diagnostics.

Sources: src/osu_server/transports/stable/web_legacy/mappers/score_submit.py:165-190, src/athena_cli/stable_verification/score_submit.py:27-38

Decryption and Parsing

Performance Calculation Pipeline

PP calculation is an asynchronous process triggered after initial score persistence. It is managed by background workers using taskiq.

Performance Execution Flow

When a worker picks up a calculation job, it follows the ExecutePerformanceCalculationUseCase.

Generating architecture diagram...

Sources: tests/unit/services/commands/scores/performance/test_execute_calculation.py:127-148, AGENTS.md:389-392

Calculation States

Calculations transition through several states to handle retries and failures:

QUEUED: Initial state after the command process requests calculation.
FETCHING_FILE: Worker is retrieving the beatmap metadata or file.
CALCULATING: Worker is running the rosu-pp-py adapter.
COMPLETED: PP and Star Rating successfully calculated and stored.
UNAVAILABLE: Permanent failure (e.g., beatmap unparseable or score data invalid).

Sources: tests/unit/services/commands/scores/performance/test_execute_calculation.py:263-289, tests/unit/services/commands/scores/performance/test_execute_calculation.py:309-340

Leaderboard Projection Reconciliation

Athena uses projections for leaderboards to ensure fast read performance. The pipeline handles two types of reconciliation:

Immediate Update: When a score is submitted, upsert_if_better is called to potentially update the beatmap_leaderboard_user_bests table.
Rebuild/Refresh: If a replacement PP calculation results in a lower PP value than the previous calculation (e.g., due to a calculator version update), the system triggers a rebuild of the user's slice to find the next best score.

Sources: tests/unit/services/commands/scores/performance/test_projection_refresh.py:30-58, tests/unit/services/commands/scores/performance/test_execute_calculation.py:192-225

Response Formatting

The pipeline concludes by mapping the SubmissionResult back to the stable client's expected text format, which includes beatmap metadata, beatmap-specific charts, and overall player charts.

Stable Chart Fields

Chart Type	Key Fields
Beatmap	`rankBefore`, `rankAfter`, `accuracyBefore`, `ppBefore`, `onlineScoreId`
Overall	`totalScoreBefore`, `rankedScoreAfter`, `ppAfter`, `achievements-new`

Sources: src/athena_cli/stable_verification/score_submit.py:40-62, src/osu_server/transports/stable/web_legacy/mappers/score_submit.py:469-509

Conclusion

Resources

AI code review
Bug Bench
AI coding statistics
Coding standards
Agents
Wikis

View on GitHub