Code Submission Pipeline

Relevant source files

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

• routes/submit_routes.py
• services/code_runner.py
• utils/security.py
• levels/level_manager.py
• templates/arena.html
• models/submission.py

Introduction

The Code Submission Pipeline is the core engine of the Debug Arena platform, responsible for receiving, validating, executing, and scoring user-submitted Python code. It acts as a bridge between the browser-based IDE and the server-side evaluation environment, ensuring that submissions are processed securely while maintaining the integrity of the competitive event.

The pipeline handles high-level tasks such as safety scanning to prevent malicious code execution, comparison of execution output against pre-defined expectations, and dynamic calculation of scores based on time and hint usage. Successfully processed submissions result in level progression and persistent record-keeping in the database.
Sources: README.md:14-23, routes/submit_routes.py:11-37

Architecture and Data Flow

The submission process follows a structured path from the frontend interface to the backend database. When a user clicks "Run & Submit", the CodeMirror editor content is transmitted via a POST request to the submission endpoint.

High-Level Execution Flow

The following diagram illustrates the sequence of events from user action to result returned.

Components and Logic

1. Security Validation

Before any execution occurs, the validate_code_safety function performs a blacklist-based scan to block dangerous modules and functions that could compromise the host system. It also enforces a maximum character limit to prevent memory-based attacks.
Sources: utils/security.py:4-19, services/code_runner.py:7-9

Feature	Constraint	Description
Forbidden Modules	os, sys, subprocess, shutil	Prevents file system and process manipulation.
Forbidden Functions	eval(), exec(), __import__	Blocks dynamic code execution and metadata access.
Length Limit	2000 Characters	Prevents excessively large submissions.
Sources: utils/security.py:6-18

2. Execution Engine

The execute_python_code service uses the subprocess module to run user code in an isolated process. It captures stdout and stderr while enforcing a strict time limit.
Sources: services/code_runner.py:11-26

• Timeout: The process is capped at 2 seconds to prevent infinite loops.
• Shell Safety: shell=False is used to prevent shell injection vulnerabilities.
• Output Capture: Captures and strips both successful output and error messages for comparison.
  Sources: services/code_runner.py:17-21

3. Scoring and Progression Logic

Scores are calculated dynamically based on three primary factors: completion, speed, and hint usage.

• Base Score: A successful submission starts with a base of 100 points.
• Time Penalty: Deducts 1 point for every 10 seconds taken to complete the level.
• Hint Penalty: If a hint was revealed via the get_hint endpoint, a level-specific penalty (defined in LEVELS) is applied.
• Persistence: On success, the Submission model records the code, time taken, and score, while the Team model is updated to the next level.
  Sources: routes/submit_routes.py:44-77, levels/level_manager.py:5-125

Data Models

The pipeline interacts with the Submission entity to log every attempt and the Team entity to track global progress.

Submission Fields

Field	Type	Description
team_id	Integer (FK)	Links the submission to a specific team.
level_id	Integer	The difficulty level being attempted.
code_submitted	Text	The actual source code provided by the user.
status	String	Result status (e.g., 'Correct').
time_taken	Integer	Seconds elapsed from level start to submission.
score_earned	Integer	Final calculated score for the level.
Sources: models/submission.py:4-13

Conclusion

The Code Submission Pipeline ensures a fair and secure competitive environment by combining strict execution limits, security filtering, and time-based scoring. By automating the evaluation against expected_output defined in the LEVELS configuration, the system provides immediate feedback to participants while maintaining persistent records for the global leaderboard.
Sources: routes/submit_routes.py:84-92, README.md:14-23