Skip to content

README.md

Latest commit

Β 

History

History
267 lines (174 loc) Β· 8.24 KB

README.md

File metadata and controls

267 lines (174 loc) Β· 8.24 KB

πŸ–₯️ 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:

πŸš€ 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. ✨