A collaborative platform for programming education. Teachers create assignments with automated test generation; students submit code that is evaluated in sandboxed Docker containers.
- Secure Authentication — JWT-based login, password recovery, role-based access (Student, Teacher, Admin)
- Bulk User Registration — CSV upload with real-time WebSocket progress streaming
- Assignment Management — Teachers upload reference solutions and test case inputs; expected outputs are generated automatically by the worker
- Sandboxed Code Execution — Submissions run in isolated Docker containers with CPU, memory, and time limits
- Multi-language Support — Java, Python, C, C++
- Two Execution Modes — Practice (inline test cases vs reference solution) and Definitive (pre-generated expected outputs)
- Output Comparison — Exact match and floating-point comparators
- Asynchronous Pipeline — Execution and test generation fully decoupled via RabbitMQ
- Object Storage — Source code, test inputs, expected outputs, and execution artifacts stored in MinIO
- API Documentation — Interactive Swagger/OpenAPI at
/swagger-ui.html - Rate Limiting — Per-endpoint throttling to prevent abuse
- CI/CD — Automated testing and coverage via GitHub Actions
┌─────────────┐ REST API ┌──────────────────────────────────────────────┐
│ Frontend │ ◄────────────► │ Backend │
│ React/TS │ │ Spring Boot · PostgreSQL · MinIO │
└─────────────┘ │ │
│ ┌──────────┐ ┌───────────────────────┐ │
│ │ Auth │ │ Assignment Service │ │
│ │ Service │ │ (upload + queue job) │ │
│ └──────────┘ └───────────┬───────────┘ │
│ ┌──────────────────────┐ │ │
│ │ Execution Service │ │ │
│ │ (load assignment, │ │ │
│ │ queue job) │ │ │
│ └──────────┬───────────┘ │ │
└─────────────┼──────────────┼────────────────┘
│ RabbitMQ │
┌─────────────▼──────────────▼────────────────┐
│ Worker │
│ Spring Boot · Docker SDK · MinIO │
│ │
│ ┌──────────────────┐ ┌─────────────────┐ │
│ │ TestExecutionSvc │ │ TestGenerationSvc│ │
│ │ (run submission) │ │ (gen outputs) │ │
│ └──────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────┘
| Queue | Direction | Purpose |
|---|---|---|
codehive_queue |
backend → worker | Student code execution jobs |
codehive_result_queue |
worker → backend | Execution results |
codehive_test_generation_queue |
backend → worker | Generate expected test outputs |
codehive_test_generation_result_queue |
worker → backend | Output generation result |
test-suites/assignments/{assignmentId}/
reference/Main.{ext} ← reference solution
tc-{testCaseId}/tc{testCaseId}.in ← test case input
tc-{testCaseId}/tc{testCaseId}.out ← expected output (worker-generated)
test-execution/execution-{executionId}/
source.{ext} ← submitted code
output/tc-{n}/stdout.txt ← actual output
output/tc-{n}/stderr.txt
submissions/assignments/{assignmentId}/submission-{id}/Main.{ext}
| Layer | Technology |
|---|---|
| Backend API | Spring Boot 3, Java 21, Spring Security, JPA/Hibernate |
| Frontend | React Router v7, TypeScript, Vite |
| Worker | Spring Boot 3, Java 21, Docker Java SDK |
| Database | PostgreSQL |
| Message Broker | RabbitMQ |
| Object Storage | MinIO |
| Auth | JWT (stateless), BCrypt |
| Testing | JUnit 5, Mockito, AssertJ |
| Docs | SpringDoc OpenAPI / Swagger |
- Java 21+
- Node.js 18+
- Docker and Docker Compose
cd codehive-backend
docker compose up -dThis starts PostgreSQL, RabbitMQ, and MinIO.
cd codehive-backend
./gradlew bootRunAvailable at: http://localhost:8080
Swagger UI: http://localhost:8080/swagger-ui.html
cd codehive-worker
./gradlew bootRunThe worker connects to RabbitMQ and MinIO on startup and begins consuming jobs.
cd codehive-frontend
npm install
npm run devAvailable at: http://localhost:3000
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /api/auth/login |
— | Login with email or enrollment number |
| POST | /api/auth/signup |
ADMIN | Create a single user account |
| POST | /api/auth/signup/csv |
ADMIN | Bulk register users from CSV |
| GET | /api/auth/me |
Bearer | Get current authenticated user |
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /api/recovery-password/forgot |
— | Request a password reset email |
| POST | /api/recovery-password/reset |
— | Reset password with token |
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /api/assignments |
TEACHER / ADMIN | Create assignment with reference solution and test inputs |
The assignment endpoint accepts multipart/form-data with three parts:
metadata— JSON with title, description, limits, comparator, languages, sampleFlagsreferenceSolution— source filetestCaseInputs— one or more input files (order determines test case index)
The assignment is created as inactive. The worker runs the reference solution against each input and stores the expected outputs. Once complete the assignment is automatically activated.
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /api/execution/check |
— | Submit code for execution |
| GET | /api/execution/check/{id} |
— | Poll execution status |
Execution request body:
{
"code": "...",
"language": "JAVA",
"executionType": "PRACTICE",
"assignmentId": "uuid",
"requesterId": "uuid",
"testCases": ["input1", "input2"]
}PRACTICE — inline test cases are compared against the reference solution output.
DEFINITIVE — submission is compared against pre-generated expected outputs from MinIO.
| Endpoint | Limit | Window |
|---|---|---|
POST /api/auth/login |
5 requests | 60 s |
POST /api/auth/signup |
3 requests | 5 min |
POST /api/recovery-password/forgot |
3 requests | 5 min |
POST /api/recovery-password/reset |
5 requests | 5 min |
POST /api/execution/check |
10 requests | 60 s |
| Status | Meaning |
|---|---|
PENDING |
Queued, not yet processed |
AC |
Accepted — all test cases passed |
WA |
Wrong Answer |
CE |
Compilation Error |
RTE |
Runtime Error |
TLE |
Time Limit Exceeded |
MLE |
Memory Limit Exceeded |
Overall verdict priority when tests fail: CE > TLE > MLE > RTE > WA.
| Language | Compile command | Run command |
|---|---|---|
| Java | javac Main.java |
java Main |
| Python | — | python main.py |
| C | gcc -o program main.c -lm |
./program |
| C++ | g++ -o program main.cpp -std=c++17 -lm |
./program |
# Backend unit and integration tests
cd codehive-backend
./gradlew test
# With coverage report
./gradlew test jacocoTestReport
open build/reports/jacoco/test/html/index.html
# Worker tests
cd codehive-worker
./gradlew test
# Frontend type check
cd codehive-frontend
npm run typecheckCodeHive/
├── codehive-backend/ ← Spring Boot REST API
│ ├── src/main/java/com/github/codehive/
│ │ ├── config/ ← RabbitMQ, MinIO, Security, WebSocket, Async
│ │ ├── controller/ ← Auth, RecoveryPassword, Assignment, CheckExecution
│ │ ├── messaging/ ← Producers and listeners for both queue pairs
│ │ ├── model/ ← Entities, DTOs, queue DTOs, requests, responses
│ │ ├── repository/ ← JPA repositories (UUID primary keys)
│ │ ├── security/ ← JWT filter, UserDetailsService
│ │ ├── service/ ← Auth, Assignment, Execution, ObjectStorage, Mail
│ │ ├── ratelimit/ ← @RateLimit annotation and aspect
│ │ ├── websocket/ ← CSV progress handler
│ │ └── utils/ ← ObjectKeyBuilder, FileExtensionUtil, JwtUtil
│ └── src/test/ ← Unit and integration tests
│
├── codehive-worker/ ← Sandboxed execution worker
│ └── src/main/java/com/github/codehive/worker/
│ ├── config/ ← Docker client, MinIO, RabbitMQ
│ ├── messaging/ ← Listeners (execution + generation) and producers
│ ├── model/ ← DTOs and enums
│ ├── sandbox/ ← LanguageExecutor interface and implementations
│ └── service/ ← TestExecutionService, TestGenerationService
│
├── codehive-frontend/ ← React Router v7 SPA
│ └── app/
│ ├── components/ ← Reusable UI and ProtectedRoute guard
│ ├── context/ ← Auth and theme providers
│ ├── pages/ ← Admin, login, recovery pages
│ ├── routes/ ← Route entry files
│ ├── services/ ← AuthService, RecoveryPasswordService
│ └── types/ ← TypeScript contracts
│
└── llms/ ← Implementation documentation for AI agents
├── backend/
├── frontend/
└── worker/
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature - Write tests for your changes
- Ensure all tests pass
- Open a Pull Request against
main
MIT — see LICENSE for details.
- Irmin Hernandez Jimenez — IrminDev
- Johann Daniel Trejo Flores — JohannTF
- Rodolfo Aparicio Lopez — rodolfo-rgb