🎓 KODIN Platform (TukeWars)

Educational coding platform for learning programming through interactive tasks and challenges

KODIN Platform is a comprehensive web-based educational system designed for teaching and learning programming. The platform supports multiple programming languages (Python, Java, C/C++), features automated code evaluation using Docker containers, classroom management, gamification through badges and leaderboards, and real-time collaboration tools.

📋 Table of Contents

Features
Technology Stack
Prerequisites
Getting Started
- Using Docker (Recommended)
- Manual Setup
Environment Configuration
Project Structure
API Documentation

✨ Features

For Students

📝 Interactive Coding Tasks - Solve programming challenges in Python, Java, and C/C++
🏆 Gamification - Earn badges, XP points, and compete on leaderboards
👥 Social Learning - Friend lists, forums, and collaborative features
📊 Progress Tracking - Monitor your learning journey with detailed statistics
🔔 Notifications - Stay updated on new tasks, achievements, and classroom activities
📚 Integrated Documentation - Access language guides and tutorials within the platform

For Teachers

🏫 Classroom Management - Create and manage multiple classes
✏️ Task Creation - Design custom programming tasks with automated tests
📈 Student Analytics - Track student progress and performance
✅ Automated Grading - Code submissions are automatically evaluated in isolated Docker containers
🔐 SSO Integration - Keycloak-based single sign-on support

Platform Features

🐳 Containerized Code Execution - Secure, isolated environment for running student code
🔄 Real-time Feedback - Instant test results and code validation
🎨 Responsive Design - Works seamlessly on desktop, tablet, and mobile devices
🔒 Secure Authentication - JWT-based authentication with email verification

🛠 Technology Stack

Frontend

Framework: React 18 with TypeScript
Styling: CSS Modules
State Management: React Context API + Hooks (useState, useEffect, useContext)
Routing: React Router v6
Build Tool: Vite
HTTP Client: Fetch API
Code Editor: Syntax highlighting with PrismJS

Backend

Runtime: Node.js
Framework: Express.js
Authentication: JSON Web Tokens (JWT), Keycloak SSO
Email Service: Mailtrap
File Uploads: Multer
Container Management: Dockerode
Security: bcrypt, CORS middleware

Database

Database: PostgreSQL 15+
Connection: node-postgres (pg)
Schema: Relational database with users, tasks, solutions, classrooms, badges, etc.

DevOps & Infrastructure

Containerization: Docker & Docker Compose
Code Execution: Isolated Docker containers for Python, Java, and C/C++
Development: Nodemon for hot-reloading
Process Management: Concurrently for running multiple services

📦 Prerequisites

Before you begin, ensure you have the following installed:

Docker Desktop (version 20.10 or higher) - Download Docker
Docker Compose (usually included with Docker Desktop)
Node.js (version 16 or higher) - Only needed for local development
Git - For cloning the repository

🚀 Getting Started

Using Docker (Recommended)

Docker Compose handles all services, dependencies, and networking automatically. This is the easiest way to get the platform running.

1. Clone the Repository

git clone <repository-url>
cd tukewars

2. Create Environment File

Create a .env file in the project root with the following configuration:

# Database Configuration
POSTGRES_USER=postgres
POSTGRES_PASSWORD=bemi1
POSTGRES_DB=TukeWars
POSTGRES_HOST=pg_data
POSTGRES_PORT=5432

# JWT Configuration
JWT_SECRET=your_super_secret_jwt_key_change_this_in_production

# Email Configuration (Mailtrap)
MAILTRAP_TOKEN=your_mailtrap_api_token

# Application URLs
FRONTEND_URL=http://localhost:3000
BACKEND_URL=http://localhost:5000

# Keycloak SSO (Optional)
KEYCLOAK_URL=your_keycloak_url
KEYCLOAK_REALM=your_realm
KEYCLOAK_CLIENT_ID=your_client_id
KEYCLOAK_CLIENT_SECRET=your_client_secret

3. Start Docker Desktop

Make sure Docker Desktop is running on your system.

4. Build and Start All Services

# Build and start all containers in detached mode
docker-compose up -d

# Build task runner images (Python, Java, C)
docker-compose --profile build-only up --build

This will start:

PostgreSQL Database on port 5432
Backend API on port 5000
Frontend on port 3000
Task Runner Images for code execution (Python, Java, C)

5. Access the Application

Frontend: http://localhost:3000
Backend API: http://localhost:5000
Database: localhost:5432 (use your PostgreSQL client)

6. View Logs

# View all logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f pg_data

7. Stop the Application

# Stop all containers
docker-compose down

# Stop and remove volumes (⚠️ this will delete database data)
docker-compose down -v

Manual Setup

If you prefer to run services individually without Docker:

1. Clone and Install Dependencies

git clone <repository-url>
cd tukewars

# Install backend dependencies
npm install

# Install frontend dependencies
cd Frontend
npm install
cd ..

2. Setup PostgreSQL Database

Install PostgreSQL and create a database, then run the initialization script:

psql -U postgres -d TukeWars -f db/dbCreate.sql

3. Configure Environment Variables

Create a .env file in the project root (see Docker section for required variables).

4. Start the Backend

npm run start:backend

Backend will be available at http://localhost:5000

5. Start the Frontend (in a new terminal)

npm run start:frontend

Frontend will be available at http://localhost:3000

6. Start Both Simultaneously

npm start

🌲 Project Structure

tukewars/
├── docker-compose.yml           # Docker orchestration configuration
├── DockerFile.Backend          # Backend container definition
├── package.json                # Root package.json for backend
├── README.md                   # This file
│
├── Backend/                    # Express.js REST API
│   ├── index.js               # Application entry point
│   ├── controllers/           # Request handlers
│   │   ├── auth.controller.js          # Authentication & registration
│   │   ├── badge.controller.js         # Badge management
│   │   ├── bugReport.controller.js     # Bug reporting
│   │   ├── classroom.controller.js     # Classroom operations
│   │   ├── friendlist.controller.js    # Friend management
│   │   ├── leaderboard.controller.js   # Rankings & statistics
│   │   ├── notification.controller.js  # User notifications
│   │   ├── solution.controller.js      # Code submission & evaluation
│   │   ├── task.controller.js          # Task CRUD operations
│   │   └── sso.controller.js          # Single sign-on
│   ├── routes/                # API endpoint definitions
│   ├── middleware/            # Authentication & authorization
│   ├── db/                    # Database connection
│   ├── mailSender/            # Email service integration
│   ├── utils/                 # Helper functions
│   └── dockerFiles/           # Code execution containers
│       ├── solutionPython/    # Python task runner
│       ├── solution/          # Java task runner
│       └── solutionC/         # C/C++ task runner
│
├── Frontend/                   # React TypeScript application
│   ├── DockerFile.Frontend    # Frontend container definition
│   ├── package.json           # Frontend dependencies
│   ├── tsconfig.json          # TypeScript configuration
│   ├── public/                # Static assets
│   │   ├── index.html
│   │   └── manifest.json
│   └── src/
│       ├── App.tsx            # Root component
│       ├── index.tsx          # Application entry
│       ├── components/        # Reusable UI components
│       │   ├── header/
│       │   ├── footer/
│       │   ├── calendar/
│       │   ├── createTask/
│       │   ├── friendlist/
│       │   ├── forum/
│       │   └── ...
│       ├── pages/             # Page components (routes)
│       ├── context/           # React Context providers
│       ├── styles/            # Global styles
│       └── assets/            # Images, icons, fonts
│
├── db/                        # Database files
│   ├── dbCreate.sql          # Database schema & initial data
│   └── DockerFile.Database   # PostgreSQL container
│
└── uploads/                   # User-uploaded files
    ├── badges/               # Badge images
    └── docs/                 # Documentation files
        ├── Authoring Guidelines.md
        ├── Badges.md
        ├── Class Management.md
        ├── Creating Tasks.md
        ├── Java.md
        ├── Python.md
        └── C.md

⚙️ Environment Configuration

The application requires several environment variables. Create a .env file in the project root:

# Database
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_DB=TukeWars
POSTGRES_HOST=pg_data
POSTGRES_PORT=5432

# JWT Authentication
JWT_SECRET=your_secret_key_minimum_32_characters_long

# Email Service (Mailtrap for development)
MAILTRAP_TOKEN=your_mailtrap_token

# Application
FRONTEND_URL=http://localhost:3000
BACKEND_URL=http://localhost:5000
NODE_ENV=development

# Keycloak SSO (Optional)
KEYCLOAK_URL=https://your-keycloak-server.com
KEYCLOAK_REALM=your-realm
KEYCLOAK_CLIENT_ID=kodin-app
KEYCLOAK_CLIENT_SECRET=your-client-secret

📡 API Documentation

The backend exposes a RESTful API on port 5000. Main endpoints:

Authentication

POST /api/auth/register - User registration
POST /api/auth/login - User login
POST /api/auth/logout - User logout
POST /api/auth/verify-email - Email verification
GET /api/auth/check - Check authentication status

Tasks

GET /api/tasks - Get all tasks
GET /api/tasks/:id - Get task by ID
POST /api/tasks - Create new task (teacher only)
PUT /api/tasks/:id - Update task (teacher only)
DELETE /api/tasks/:id - Delete task (teacher only)

Solutions

POST /api/solutions/submit - Submit code solution
GET /api/solutions/user/:userId - Get user's solutions
GET /api/solutions/task/:taskId - Get solutions for a task

Classrooms

GET /api/classrooms - Get all classrooms
POST /api/classrooms - Create classroom (teacher only)
POST /api/classrooms/:id/join - Join classroom
GET /api/classrooms/:id/students - Get classroom students

Leaderboard

GET /api/leaderboard/global - Global rankings
GET /api/leaderboard/classroom/:id - Classroom rankings

Users

GET /api/users/profile - Get user profile
PUT /api/users/profile - Update profile
GET /api/users/stats - Get user statistics

For complete API documentation, see the individual controller files in Backend/controllers/.

🐛 Troubleshooting

Docker Issues

Problem: docker-compose up fails with port conflicts

# Solution: Stop services using those ports or change ports in docker-compose.yml
docker-compose down
# Check what's using the port
netstat -ano | findstr :5000

Problem: Database connection refused

# Solution: Wait for database to be healthy
docker-compose logs pg_data
# Restart services
docker-compose restart backend

Problem: Changes not reflecting

# Solution: Rebuild containers
docker-compose up --build

Development Issues

Problem: MODULE_NOT_FOUND errors

# Solution: Reinstall dependencies
npm install
cd Frontend && npm install

Problem: Database schema errors

# Solution: Reset database
docker-compose down -v
docker-compose up -d pg_data
# Wait for database to initialize
docker-compose up -d

🧪 Testing

Automated testing is currently in development. For manual testing:

Code Execution: Submit Python/Java/C solutions through the UI
Authentication: Test registration, login, email verification
Classroom Management: Create classes, add students, assign tasks
Leaderboard: Verify XP calculations and rankings

📦 Building for Production

Frontend Build

cd Frontend
npm run build

Production files will be in Frontend/build/

Backend Production

The backend runs with Node.js. For production deployment:

# Use PM2 or similar process manager
npm install -g pm2
pm2 start Backend/index.js --name kodin-backend

Docker Production Build

docker-compose -f docker-compose.prod.yml up -d

📚 Additional Documentation

For more detailed information:

⚠️ Important: Make sure Docker Desktop is running before executing docker-compose up

Name		Name	Last commit message	Last commit date
.vscode		.vscode
Backend		Backend
Frontend		Frontend
db		db
uploads		uploads
.gitignore		.gitignore
DockerFile.Backend		DockerFile.Backend
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation