Dependencies & Environment

Relevant source files

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

• README.md
• app.py
• database/init_db.py
• models/team.py
• services/code_runner.py
• templates/base.html
• templates/arena.html

Introduction

The Dependencies & Environment of the Debug Arena platform encompass the core technological stack, configuration management, and the runtime environment necessary to host a competitive debugging event. The system is built using a Python-based Flask backend, utilizing a relational database for state persistence and a modern frontend stack for a real-time, responsive user experience.

The environment is specifically designed to support secure code execution, proctoring enforcement via browser APIs, and dynamic level management. It transitions from local development using SQLite to a production-ready state using environment variables for sensitive configurations like database URIs and secret keys.

Sources: README.md:54-70, app.py:16-29

Tech Stack Overview

The platform utilizes a multi-layered architecture consisting of backend services, frontend interfaces, and database management.

Backend & Core Logic

• Python: Core programming language for application logic.
• Flask: Web framework used for routing, sessions, and request handling.
• SQLAlchemy: ORM for database interactions and schema management.
• Subprocess: Standard library used to execute submitted Python code in a controlled environment.

Frontend & UI

• HTML5 / Jinja2: Templating engine for dynamic content rendering.
• Tailwind CSS: Utility-first CSS framework for responsive design.
• JavaScript: Logic for the Proctoring system and real-time UI updates.
• CodeMirror: In-browser IDE for code editing.
• Canvas-Confetti: Client-side library for victory celebrations.

Database

• SQLite: Primary database for development, stored in the instance/ directory.
• PostgreSQL: Mentioned as the production-ready target.

Sources: README.md:72-87, app.py:10-14, templates/base.html:10-15, templates/arena.html:190-192

Environment Configuration

The application uses Flask configuration objects to manage its operational environment. It prioritizes environment variables for security and flexibility, falling back to local defaults for development.

Configuration Key	Source	Default / Fallback	Purpose
SECRET_KEY	os.getenv('SECRET_KEY')	'dev-key-123'	Session signing and security.
SQLALCHEMY_DATABASE_URI	os.getenv('DATABASE_URL')	sqlite:///.../instance/db.sqlite3	Database connection string.
SQLALCHEMY_TRACK_MODIFICATIONS	Hardcoded	False	Disables overhead of event tracking.

Sources: app.py:19-29

Directory Structure Requirements

The environment requires specific directory structures to be present for successful initialization:

• Project Root: Base directory for application code.
• instance/: Created automatically by app.py to house the SQLite database file.
• database/: Used by initialization scripts to ensure database pathing.

Sources: app.py:32-37, database/init_db.py:12-14

System Architecture Flow

The following diagram illustrates the interaction between the client environment and the backend evaluation engine.

Execution Environment & Constraints

The Code Runner service defines the constraints of the runtime environment for user-submitted code. To prevent malicious activity or resource exhaustion, the environment imposes strict limits:

1. Safety Scan: Code is checked against a blacklist of forbidden modules and functions (e.g., os, subprocess, eval).
2. Time Limit: A hard limit of 2 seconds is enforced on code execution via subprocess.run to prevent infinite loops.
3. Shell Isolation: Code is executed with shell=False to prevent shell injection attacks.
4. Length Limit: Code submissions are capped at 2000 characters to prevent memory-based attacks.

Sources: services/code_runner.py:15-22, utils/security.py:5-18

Database Initialization

The database environment is initialized through a standalone script that sets up the schema based on the SQLAlchemy models defined in the project.

# database/init_db.py:16-18
with app.app_context():
    db.create_all()
    print("✅ Database initialized successfully at database/db.sqlite3")

Sources: database/init_db.py:16-18, models/team.py:5-25

Conclusion

The Dependencies & Environment of Debug Arena provide a robust foundation for competitive coding. By combining a Flask-based backend with strict execution controls and browser-level proctoring, the platform ensures a secure and standardized environment for all participants. The use of environment variables and automated directory management facilitates easy deployment across different hosting environments.