Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Python Debug Arena is a real-time competitive debugging platform designed for live coding events. It facilitates a high-pressure environment where teams identify and fix logical and syntactical bugs in Python code while adhering to strict anti-cheat and proctoring rules. The system integrates automated code evaluation, a persistent scoring system, and a client-side security layer to ensure event integrity. Sources: README.md:3-8, README.md:14-17
The architecture follows a modular Flask-based structure, utilizing SQLAlchemy for ORM-based data persistence and CodeMirror for the interactive browser-based IDE. The core logic is distributed across specialized route handlers, a centralized level manager, and a secure code execution service. Sources: README.md:52-58, app.py:43-46
Core Components
The system is divided into several functional blocks that handle different aspects of the competition:
- Authentication & Session Control: Manages team registration and secure logins using hashed passwords. Sources: routes/auth_routes.py:8-58
- Proctoring & Anti-Cheat: A client-side JavaScript layer (
proctor.js) that enforces fullscreen mode and detects tab switching. Sources: static/js/proctor.js:1-73 - Evaluation Engine: Executes user-submitted code in a controlled subprocess environment and validates the output against expected results. Sources: services/code_runner.py:5-35
- Level Management: A centralized dictionary-based store (
LEVELS) containing level metadata, buggy code, hints, and penalties. Sources: levels/level_manager.py:3-134 - Leaderboard & Scoring: Real-time calculation of points based on completion time and hint penalties. Sources: routes/submit_routes.py:46-55
High-Level System Flow
The diagram below illustrates the flow of a user request through the various architectural layers, from security enforcement to code execution.
The flow ensures that security violations are checked both client-side and via middleware before any code reaches the execution engine. Sources: README.md:70-80, services/code_runner.py:5-20
Proctoring and Security System
The proctoring system is responsible for maintaining the integrity of the competitive environment. It uses proctor.js to monitor the user's browser state and communicates violations to the backend. Sources: static/js/proctor.js:4-6
Violation Logic
- Fullscreen Enforcement: Participants must play in fullscreen mode. Exiting fullscreen triggers a violation. Sources: static/js/proctor.js:58-62
- Tab Switching Detection: Using the
visibilitychangeAPI, the system detects if the user navigates away from the arena tab. Sources: static/js/proctor.js:64-68 - Disqualification Threshold: Teams are allowed up to 2 violations. The 3rd violation leads to automatic disqualification. Sources: static/js/proctor.js:5, routes/arena_routes.py:115-126
Violation Log Sequence
Code Evaluation Service
Code execution is handled by the execute_python_code function, which wraps standard Python execution in multiple security layers. Sources: services/code_runner.py:5
Security Constraints
| Constraint | Implementation Detail | Purpose |
|---|---|---|
| Safety Scan | Blacklist of modules (os, sys, subprocess) and functions (eval, exec). | Prevents system-level attacks and unauthorized access. |
| Time Limit | 2-second timeout via subprocess.run. | Prevents Denial of Service via infinite loops. |
| Length Limit | Maximum of 2000 characters. | Prevents memory-based attacks. |
| Isolation | shell=False in subprocess call. | Prevents shell injection. |
Sources: utils/security.py:5-18, services/code_runner.py:7-20
Data Model and Persistence
The system uses SQLAlchemy to manage the team and submission entities. The Team model tracks the current progress and security status, while Submission records individual level results. Sources: models/team.py:5-24, routes/submit_routes.py:70-77
Entity Relationship Diagram
Level and Scoring Logic
Levels are managed centrally to ensure consistency across the application. The LEVELS object defines the "ground truth" for each challenge. Sources: levels/level_manager.py:5-134
Scoring Algorithm
Points for each level are calculated dynamically upon successful submission:
- Base Points: 100 points per level. Sources: routes/submit_routes.py:47
- Time Penalty: 1 point deducted for every 10 seconds elapsed. Sources: routes/submit_routes.py:48
- Hint Penalty: If a hint is used, the level's specific penalty value (e.g., 15 or 30 points) is deducted. Sources: routes/submit_routes.py:51-54, levels/level_manager.py:16
- Hard Minimum: A successful submission always grants at least 30 points. Sources: routes/submit_routes.py:55
Level Metadata Table
| Level | Difficulty | Penalty | Goal / Objective |
|---|---|---|---|
| 1 | Easy | 15 | Correct syntax for print and parentheses. |
| 3 | Easy-Medium | 10 | Fix logic in a pricing/discount conditional. |
| 5 | Medium | 20 | Debug username validation loop/return logic. |
| 7 | Hard | 25 | Optimize Fibonacci calculation (Timeout fix). |
| 8 | Hard | 30 | Fix matrix transpose indexing. |
Sources: levels/level_manager.py:5-134
Summary
The Python Debug Arena architecture prioritizes event integrity through its multi-layered security approach, combining client-side proctoring with backend code validation. By centralizing level definitions and utilizing a persistent ORM-based data model, the system maintains a consistent state for competitive real-time leaderboards. Sources: README.md:20-40, app.py:20-60