🖥️ CodeExecutor-API

A professional, layered-architecture API for dynamic code execution. This project allows you to run code in multiple languages against database-backed problems and test cases. 🚀🧪

---

🛠️ Prerequisites

Before embarking on this journey, ensure your machine is equipped with:

• 🐳 Docker: Install Docker
• 🐳 Docker Compose: Install Docker Compose

---

🚀 Step-by-Step Setup Guide

Follow these steps to get your own instance of CodeExecutor-API up and running in minutes!

1️⃣ Clone the Repository

Open your terminal and clone this project:

git clone https://github.com/Saannddy/CodeExecutor-API
cd CodeExecutor-API

2️⃣ Configure Environment ⚙️

The project uses a .env file for configuration. Copy the example to get started:

cp .env.example .env

(You can tweak the DATABASE_URL or ports inside .env if needed, but defaults work perfectly!)

3️⃣ Build and Launch 🏗️

Run the entire stack (API + PostgreSQL DB) using Docker Compose:

## FOR LOCAL DB
docker compose --profile local up -d --build
## FOR PRODUCTION
docker compose --profile remote up -d --build

## FOR REBUILD WHILE DOCKER STILL RUNNING
docker compose --profile local up -d --build --force-recreate

• -d: Runs containers in the background (detached mode).
• --build: Ensures all recent code changes are freshly compiled.

5️⃣ Automatic Initialization 🪄

On the very first run, the system will automatically:

• Create all database tables (using UUIDs for safety).
• Seed 7+ coding problems (Two Sum, Palindrome, etc.).
• Link problems with their respective categories and tags.

---

🏗️ Database Management

While the system handles initialization automatically, you may need these manual commands for development:

🔄 Migrations (Alembic)

If you modify the models in src/models/, use these commands to sync the database:

• Check Status: docker compose --profile local exec code-api alembic current

• Apply Migrations: docker compose --profile local exec code-api alembic upgrade head

• Generate New Migration:

  docker compose --profile local exec code-api alembic revision --autogenerate -m "description_of_change"

🌐 Cloud Database Migration (NeonDB)

If you want to connect to NeonDB online and migrate it to the latest version:

1. Get Connection String: Copy your connection string from the Neon Console (ensure ?sslmode=require is included).

2. Apply Migrations: Run the following command, replacing YOUR_NEON_URL with your actual connection string:

   docker compose --profile local exec -e DATABASE_URL="YOUR_NEON_URL" local-code-api alembic upgrade head

3. (Optional) Seed Data: If your Neon database is empty, you can seed it with the default problems:

   docker compose --profile local exec -e DATABASE_URL="YOUR_NEON_URL" local-code-api python3 -m scripts.seed

(Alternatively, you can simply update the DATABASE_URL in your .env file and run the standard migration commands.)

🌱 Data Seeding & Cleanup

For manual data management, use these commands from the project root:

1️⃣ Java Restroom Seeding (40+ Questions & Riddles)

Seed the database with Java MCQs, riddles, and problems tagged as JAV_RESTROOM:

# Running via Docker (Must rebuild if scripts are modified)
docker compose --profile local up -d --build
docker compose --profile local exec local-code-api python3 -m scripts.seeders.seed_restroom_java
docker compose --profile remote exec code-api python3 -m scripts.seeders.seed_restroom_java
docker compose --profile remote exec code-api python3 -m scripts.seeders.seed_lockerroom_java
docker compose --profile remote exec code-api python3 -m scripts.seeders.seed_hallway_java
docker compose --profile remote exec code-api python3 -m scripts.seeders.seed_elevatorhall_java

# Running Locally (Ensure .env is configured or set DATABASE_URL)
export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/code_executor
PYTHONPATH=src python3 src/scripts/seeders/seed_restroom_java.py

2️⃣ Clear All Database Data

Delete all entries from all tables (Riddles, Questions, Problems, etc.):

# Running via Docker
docker compose --profile local exec local-code-api python3 -m scripts.delete

# Running Locally
export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/code_executor
PYTHONPATH=src python3 src/scripts/delete.py

3️⃣ Standard Sample Seeding

Seed the original set of coding problems (Two Sum, etc.):

# Running via Docker (Recommended)
docker compose --profile local exec local-code-api python3 -m scripts.seed

# Running Locally
export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/code_executor
PYTHONPATH=src python3 src/scripts/seed.py

---

️ Recommended Tooling

For the most professional development experience, we recommend the following tools:

• ⚡ OrbStack: A fast, light, and easy way to run Docker containers on macOS.
• 🐝 Beekeeper Studio: A smooth and easy-to-use SQL editor and database manager for PostgreSQL.
• 🐶 Bruno: A fast and git-friendly API client for testing the CodeExecutor endpoints.

---

�📖 Complete API Documentation

Since you're up and running, you'll want to know how to talk to the API!

• Detailed Endpoints: See API_DOCUMENTATION.md for full request/response examples.
• Interactive Swagger/Scalar Docs: Visit http://localhost:3000/docs while the app is running.
• OpenAPI Spec: Available at http://localhost:3000/openapi.yaml.

---

� Testing with Bruno

For the best developer experience, we've included a Bruno Collection:

1. Open Bruno.
2. Import the folder located at ./bruno.
3. Start firing requests!

---

🧪 Supported Languages

• 🐍 Python (python)
• 🟨 JavaScript (javascript)
• ☕ Java (java)
• 🟦 C (c)
• 🟥 C++ (cpp)

---

🧪 Testing

Tests are organized by feature group in the tests/ directory:

tests/
├── conftest.py           # Shared fixtures (Flask client, DB mocks)
├── problem/              # Problem endpoint tests
│   └── test_problem_handler.py
├── question/             # Question endpoint tests
├── riddle/               # Riddle endpoint tests
├── execution/            # Code execution tests
└── docs/                 # Documentation endpoint tests

Run with Coverage Report

The tests automatically generate an HTML report inside the container. To view it locally:

# 1. Run the tests
docker compose --profile local exec local-code-api python3 -m pytest

# 2. Copy the report from the container to your machine
docker cp codeexecutor-api-local-code-api-1:/usr/src/app/coverage/ ./coverage/

# 3. Open it
open coverage/index.html

The report highlights exactly which lines were hit or missed during testing — click any file to see line-by-line coverage.

Run Locally (Outside Docker)

If you want to run tests without Docker for faster iteration:

1. Install Dependencies:

   pip install Flask gunicorn pytest sqlmodel alembic python-dotenv pydantic-settings esprima javalang pytest-cov pybars3

   (Note: psycopg2-binary might fail on some Python versions, but unit tests are mocked so you can skip it.)

2. Run Tests:

   PYTHONPATH=src python3 -m pytest

3. View Coverage:

   open coverage/index.html

Run a Specific Test Group

PYTHONPATH=src python3 -m pytest tests/problem/

Note: Tests mock the database layer automatically, so no local Postgres is required.

---

📝 Usage Best Practices

• 💡 4 Spaces: Always use spaces instead of tabs in your JSON code strings.
• ⏱️ Timeouts: Most problems are capped at 5 seconds for safety.
• 🔒 Sandboxing: Code runs in a dedicated non-root container environment.

---

Build with focus on Modular, Scalable, and Professional architecture. ✨